Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

466 lines (339 sloc) 15.889 kb

Java Spring Lobby Server


This software is a lobby server for the Spring RTS engine. You may think of it as something similar to an IRC server with additional protocol instructions to manage battles.

Historically seen, this was the first, and till 2010 also the main/official lobby server implementation.

This repository also contained two other tiny applications, which were removed in 2010, because they were no longer of use alone or in combination with the lobby server:

  • TransferOldAccounts
  • WebServer


Maven is used as the project management system. The project description file is pom.xml, which contains everything Maven needs to know about the project, in order to:

  • Download dependencies
  • Compile the sources
  • Pack the class files together with all the dependencies into a single, executable jar file

Installing Maven 2

In case you already have it installed, skip this paragraph.

  • Windows

    Download the latest stable version (not the source) here. Then extract to eg. your C:\Program Files, and make sure the bin sub-dir of the extracted folder is in your PATH environment variable.

  • Unix, Linux, BSD, OS X

    Install the maven2 package in your systems way of doing so. On Ubuntu for example, you would do this:

    > sudo apt-get install maven2

Building the software

  1. Make sure you have Maven 2 installed. You can check that with the following command:

    > mvn --version
  2. compile and package:

    > mvn package

    This may take quite some time, if you are running Maven for the first time, as it has to download all the dependencies for the different build steps, plus our own dependencies.

If everything went smoothly, this was it already!

All the output of the build process is under the target sub-dir. This is also where you find the final jar files: target/springls*.jar


Use or runServer.bat to start the server, if you built it with Maven. You should also see the documentation in these files, for further info.

When server is up and running, people from the local network will be able to join it as well as people from the internet, although those from the internet will not be able to join games hosted by local clients, still local clients will be able to join games hosted by outside players. You do not need to create any accounts when joining a LAN server, it will accept any user-name/password.

If you experience problems using server in LAN mode (like other clients being timed-out when connecting to your game), you should try this: Let the player who is NOT running the server host. This is important when the server assigns a player (who is using the same computer as the server) the localhost IP ( In this case, other players on the LAN would receive this IP and when they try to connect to the game host at, the connection attempt will fail. The server should replace this IP with a local one (192.168.x.y) automatically, but if it fails for any reason, you should use the method described above.

To be able to accept connections from outside the LAN, you will have to forward ports 8200 (TCP) and 8201 (UDP) to the machine running the lobby.

You will also need the Java run-time environment (JRE) 6 or later. The latest version can be found here.

Command line arguments

Example of usage:

> java -jar springls-*.jar --port 8200 --nat-port 8201 --log-main

Arguments are case sensitive. For the full list of arguments, use --help.

To stop the server, issue [Ctrl]+[C].

Running with a DB

Normal mode means, using a database or a flat file for storing the user accounts. This is how you prepare for using a database:


> # copy the configuration template
> cp conf/META-INF/persistence.xml.template conf/META-INF/persistence.xml
> # edit the configuration
> ${EDITOR} conf/META-INF/persistence.xml


> # copy the configuration template
> copy conf\META-INF\persistence.xml.template conf\META-INF\persistence.xml
> # edit the configuration
> notepad conf\META-INF\persistence.xml

Info about the default persistence provider: Hibernate configuration

When you are using MySQL, and you are experiencing problems to authenticate on the DB, have a look here. Instead of localhost.localdomain, you may face the same problem with

You have to use the --database switch on the command-line, because otherwise the server will run in LAN-mode, and not use the DB.

Release (devs only)

Prepare "target/" for the release process

mvn release:clean

Prepare the release

  • asks for the version to use
  • packages
  • signs with GPG
  • commits
  • tags
  • pushes to origin

    mvn release:prepare

Perform the release (main part)

  • checks-out the release tag
  • builds
  • deploy into sonatype staging repository
  • uploads artifacts to the github download section

    mvn release:perform

Release the site

  • generates the site, and pushes it to the github gh-pages branch, visible under

      git checkout <release-tag>
      mvn site
      git checkout master

Promote it on Maven

Moves it from the sonatype staging to the main sonatype repo

  1. using the Nexus staging plugin:

    mvn nexus:staging-close
    mvn nexus:staging-release
  2. ... alternatively, using the web-interface:

    • firefox
    • login
    • got to the "Staging Repositories" tab
    • select "com.springrts..."
    • "Close" it
    • select "com.springrts..." again
    • "Release" it


  • A Client may participate in only one battle at the same time. If he is hosting a battle, he may not participate in other battles at the same time. The server checks for that automatically.

  • Lines sent and received may be of any length. It has been tested with 600 KB long strings and it worked in both directions. Nevertheless, commands like "CLIENTS" still try to divide data into several lines, just to make sure the client will receive them. Since the Delphi lobby client (TASClient) now supports lines of any length, dividing data into several lines is not needed anymore. Though, we keep it just in case, to be compatible with other clients which may emerge in the future. I do not divide data when sending info on battles and clients in battles. This lines may get long, but not longer than a couple of hundred bytes (they should always be under 1 KB in length).

  • Sentences must be separated by TAB characters. This also means there should be no TABs present in your sentences, since TABs are delimiters. That is why you should always replace any TABs with spaces (2 or 8 usually).

  • Syncing works by clients comparing host's hash code with their own. If the two codes match, client should update his battle status and this way telling other clients in the battle that he is synced (or unsynced otherwise). The hash code comes from hashing the mod's file and probably all the dependences too. See unitsync documentation for details.

  • Try not to edit the account file manually! If you do, do not forget that access numbers must be in binary form!

  • Team colors are currently set by players, perhaps it would be better if only the host would be able to change them?

  • Whenever you use killClient() within a for loop, do not forget to decrease loop counter as you will skip next client in the list otherwise. This was the cause for some of the "ambiguous data" errors. Or better, use the killClientDelayed() method.

  • Note that access to long's is not guaranteed to be atomic, but you should use synchronization anyway, if you use multiple threads.


Great article on how to handle network timeouts in Java:

Another one on network timeouts and alike:

Great article on thread synchronization:

Throwing exceptions:

Sun's tutorial on sockets:

How to redirect program's output by duplicating handles in windows' command prompt:

How to get local IP address (like "" and not ""):

ip-to-country databases:

Another set of 232 country flags:

Some source code on how to build client-server with java.nio classes; Betalord used code from the first link, found through the second:

Source for some simple threaded UDP server:

How to properly document thread-safety when writing classes:

Good article on immutables (like String etc.):

General info on thread-safety in java:

How to use ZIP with java:

How to download file from URL:

Very good article on exceptions:

Short introduction to generics in JDK 1.5.0:


The primary NAT traversal technique that this lobby server implements is hole punching. See these links for more info:

See the source code for implementation details.


The most recent lobby protocol specification can be found here:



For detailed changes after 0.35, please see the SCM commit messages.


  • added 'servermode' argument to TASSERVER command


  • message IDs are now actually working


  • added "update properties" (updateProperties object)


  • added option to mute by ip
  • replaced CLIENTPORT command with CLIENTOIPPORT command and also removed ip field from the ADDUSER command (this way IPs are no longer public unless you join a battle that uses nat traversal, where host needs to know your ip in order for the nat traversal trick to work)


  • added new bot mode for accounts (increases traffic limit when using bot mode)


  • added MAPGRADES command
  • added FORCESPECTATORMODE command


  • fixed some charset bug
  • added UPDATEMOTD command
  • fixed small bug with JOINBATTLE command not checking if battle is already in-game
  • fixed minor bug with mute entries not expiring on the fly


  • added -LANADMIN switch
  • modified protocol to support arbitrary colors (RGB format)


  • channel mute list now gets updated when user renames his account


  • added SETCHANNELKEY command, also modified JOIN command to accept extra argument for locked channels
  • added FORCELEAVECHANNEL command
  • LEFT command now contains (optional) "reason" parameter
  • replaced CHANNELS command with CHANNEL and ENDOFCHANNELS commands (see protocol description)
  • limited maximum length of chat messages


  • added CHANGEPASSWORD command
  • GETINGAMETIME now also accepts no argument (to return your own in-game time)
  • CHANNELTOPIC command now includes author name and time
  • added -LOGMAIN switch
  • added GETLASTIP command, FINDIP is available to privileged users as well now
  • fixed bug with /me being available even after being muted
  • CHANNELMESSAGE command now available to moderators as well


  • fixed RING command not working for battle hosts


  • integrated ploticus graphics generator and a simple web server to give access to server's statistics.
  • fixed RING command (only host can ring players participating in his own battle, unless the target is host himself)
  • fixed KICK command so that now player who's been kicked is notified about it (also kick command accepts "reason" string now)
  • added "GETLASTLOGINTIME" command (for moderators)
  • fixed bug with clients behind same NAT not getting local IPs in certain cases
  • added simple UDP server to help with NAT traversing (see
  • added UDPSOURCEPORT, CLIENTPORT and HOSTPORT commands (used with NAT traversing)


  • fixed bug with server allowing clients to have several battles open at the same time


  • improved server code (meaning less "ambigious" commands)
  • added RENAMEACCOUNT command, also userName may now contain "[" and "]" characters
  • added CHANNELMESSAGE command
  • added MUTE, UNMUTE and MUTELIST commands
  • clients behind same NAT now get local IPs instead of external one (from the server). This should resolve some issues with people playing games behind same NAT.
  • added "agreement"


  • multiple mod side support (battle status bits have changed)
  • user who flood are now automatically banned by server


  • server now keeps in-game time even after player has reached maximum level (max. in-game time server can record is 2^20 minutes)
  • rewrote the network code to use java.nio classes. This fixes several known problems with server and also fixes multiplayer replay option.
  • implemented simple anti-flood protection
  • removed old file transfer commands


  • added new host option - diminishing metal maker returns
  • switched to Webnet77's ip-to-country database, which seems to be more frequently updated:
  • added "locked" parameter to UPDATEBATTLEINFO command
  • added "multiplayer replays" support


  • fixed small bug with server not updating rank when maximum level has been reached
  • added ban list


  • added OFFERUPDATEEX command
  • added country code support
  • added simple protection against rank exploiters
  • added cpu info (LOGIN command now requires additional parameter)
  • limited usernames/passwords to 20 chars


  • fixed issue with server not notifying users about user's rank on login
  • added command: CHANNELTOPIC


  • added FORCETEAMCOLOR command
  • fixed bug which allowed users to register accounts with userName/password containing chars from 43 to 57 (dec), which should be numbers (the correct number range is 48 to 57). Invalid chars are "+", ",", "-", "." and "/".
  • added ranking system


  • added AI support
  • added KICKUSER command (admins only)
  • fixed bug when server did not allow client to change its ally number if someone else used it, even if that was only a spectator.
  • added away status bit
  • fixed bug when server denied request to battle, if there were maxplayers+1 players already in the battle.
  • added some admin commands
  • changed registration process so that now you can't register userName which is same as someone elses, if we ignore case. Usernames are still case-sensitive though.
Jump to Line
Something went wrong with that request. Please try again.