A spring lobby server written in Java (unmaintained, please use https://github.com/spring/uberserver )
README
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:
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:
You need Maven version 2 or later.
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
Make sure you have Maven 2 or later installed.
You can check that with the following command:
> mvn --version
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
The minimum requirement is the Java run-time environment (JRE) 6 or later.
The latest version can be found
here.
Use runServer.sh (Unix, Linux, BSD, OS X) or runServer.bat (Windows)
to start the server if you built it with Maven.
You should also see the documentation in these files, for further info.
When the 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, local clients in turn
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 the 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 (127.0.0.1). In this case, other players on the LAN would
receive this IP, and when they try to connect to the game host at 127.0.0.1,
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.
To configure logging details, for example using a higher verbosity level,
you have to create a custom config file.
If you are using the runServer.* script,
this is done most easily using the following steps:
Unix, Linux, BSD, OS X
cp src/main/resources/logback.xml conf
${EDITOR} conf/logback.xml
Windows
copy src\main\resources\logback.xml conf
notepad conf\logback.xml
For documentation about logback configuration,
see this link.
In additiona to the --database command line parameter,
you need to tell the server which database connection to use
for storing account- and other info,
by configuring JPA (Java Persistence API) details.
If you are using the runServer.* script,
this is done most easily using the following steps:
Unix, Linux, BSD, OS X
cp conf/META-INF/persistence.xml.template conf/META-INF/persistence.xml
${EDITOR} conf/META-INF/persistence.xml
Windows
copy conf\META-INF\persistence.xml.template conf\META-INF\persistence.xml
notepad conf\META-INF\persistence.xml
Info about the default persistence provider (Hibernate)
can be found here.
Example of usage:
> java -jar springls-*.jar --port 8200 --nat-port 8201
Arguments are case sensitive.
For the full list of arguments, use --help.
To stop the server, issue [Ctrl]+[C].
Normal mode means, using a database or a flat file for storing the user accounts.
This is how you prepare for using a database:
Unix:
> # 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
Windows:
> # 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 127.0.0.1.
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.
To release a development version to the Sonatype snapshot repository only:
mvn clean deploy -Dgithub.downloads.dryRun=true
mvn release:clean
asks for the version to use
packages
signs with GPG
commits
tags
pushes to origin
mvn release:prepare
checks-out the release tag
builds
deploy into sonatype staging repository
uploads artifacts to the github download section
mvn release:perform
generates the site, and pushes it to the github gh-pages branch,
visible under http://spring.github.com/SpringLS/
git checkout <release-tag>
mvn site
git checkout master
Moves it from the sonatype staging to the main sonatype repo
using the Nexus staging plugin:
mvn nexus:staging-close
mvn nexus:staging-release
… alternatively, using the web-interface:
Try not to edit the account file manually! If you do, do not forget that
access numbers must be in binary form!
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:
http://www.javacoffeebreak.com/articles/network_timeouts/
Another one on network timeouts and alike:
http://www.mindprod.com/jgloss/socket.html
Great article on thread synchronization:
http://today.java.net/pub/a/today/2004/08/02/sync1.html
Throwing exceptions:
http://java.sun.com/docs/books/tutorial/essential/exceptions/throwing.html
Sun’s tutorial on sockets:
http://java.sun.com/docs/books/tutorial/networking/sockets/
How to redirect program’s output by duplicating handles in windows’ command
prompt:
http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/redirection.mspx
How to get local IP address (like “192.168.1.1” and not “127.0.0.1”):
http://forum.java.sun.com/thread.jspa?threadID=619056&messageID=3477258
ip-to-country databases:
http://ip-to-country.webhosting.info
http://software77.net/cgi-bin/ip-country/geo-ip.pl
Another set of 232 country flags:
http://www.ip2location.com/free.asp
Some source code on how to build client-server with java.nio classes;
Betalord used ChatterServer.java code from the first link, found through the
second:
http://brackeen.com/javagamebook/ch06src.zip
http://www.gamedev.net/community/forums/topic.asp?topic_id=318099
Source for some simple threaded UDP server:
http://java.sun.com/docs/books/tutorial/networking/datagrams/example-1dot1/QuoteServerThread.java
How to properly document thread-safety when writing classes:
http://www-128.ibm.com/developerworks/java/library/j-jtp09263.html
Good article on immutables (like String etc.):
http://macchiato.com/columns/Durable2.html
General info on thread-safety in java:
http://mindprod.com/jgloss/threadsafe.html
How to use ZIP with java:
http://java.sun.com/developer/technicalArticles/Programming/compression/
How to download file from URL:
http://schmidt.devlib.org/java/file-download.html
Very good article on exceptions:
http://www.freshsources.com/Apr01.html
Short introduction to generics in JDK 1.5.0:
http://java.sun.com/j2se/1.5.0/docs/guide/language/generics.html
The primary NAT traversal technique that this lobby server implements is
hole punching. See these links for more info:
http://www.brynosaurus.com/pub/net/p2pnat/
http://www.potaroo.net/ietf/idref/draft-ford-natp2p/
http://www.newport-networks.com/whitepapers/nat-traversal1.html
See the source code for implementation details.
The most recent lobby protocol specification can be found here:
https://github.com/spring/LobbyProtocol
For detailed changes after 0.35, please see the SCM commit messages.