Technical Documentation

Instructions for release 1.3




Make your own levels

The level files are in the bubbob/levels subdirectory. They come in two flavours: .bin and .py. The former are MacBinary files from the original MacOS9 game. The latter are the levels that we did ourselves. To make new levels, copy for example CompactLevel.py to a new name, and open it with any text editor. The structure should be fairly simple to understand even without knowledge about Python. Just don't try to look at RandomLevels.py first :-)




Notes on the server

The server is the single program that computes all the game for all the players, but doesn't display anything. It should be run on the fastest machine, or even better on another machine of your local network where no one is playing (although modern computers don't have any trouble running both the server and a client).

The server can be run in the command-line only; try cd bubbob and python bb.py --help.




Notes on the client

If you want to understand a bit more what's going on with all these different ways to run the client (display) part, read on. The client will run in any one of the following -- make sure you do have one of these, in order of preference:

The client can also be run from the command-line; try cd display and python Client.py --help.




Troubleshooting




Network port configuration

First note that if a local connexion doesn't work, you should try using the meta-server:

If it doesn't help, and if you're technically inclined, read on.


Local connexions: if you cannot see a server in the list of local servers, then:

During a normal connexion (not going through the meta-server) the client needs to open a TCP connexion to the server. The server can be configured to listen to a specific port ("TCP server port" of the configuration page) if you can let this port in through a firewall or router.

Servers listen to HTTP as well. This is used for both the local BubBob pages (if you have a very restrictive firewall on your own machine then you might not be able to connect to your own machine, unless you let that port through) and for remote clients to which the server sends a Java applet. You can force a port in "HTTP server port". It default to 8000 if this port is free.

The server sends UDP datagrams to the clients during the game; if these ones don't pass through, they are re-routed over TCP, so it should just work. Nevertheless you might prefer UDP for responsiveness. The client can choose on which UDP port it will listen for incoming datagrams ("client incoming UDP port" of the configuration page) if you can let this port in through the firewall.

If a client has no way to establish a direct connexion but has an ssh account on a machine near the server, he can do:
ssh somewhere.domain.org -L1234:servername:4321
where servername:4321 is the full name of the server, and 1234 is some randomly choosen local port. Then you can connect BubBob to 127.0.0.1:1234 using the Go button on the main page. In this setting, if you can still let UDP datagrams enter, then configure "client incoming UDP port" to be not only the port but the whole name of the machine (or router) that the server must send the datagrams to.


Meta-server connexions: Connexions using the meta-server (with the "Internet server page" from BubBob's main page) work generally better, as long as the server and the client can independently connect to the meta-server (which is at codespeak.net using TCP ports 8050 and 8055). Firewalls and routers generally allow this. The meta-server will then co-operate with the server and the client to synchronize their connexion. (The meta-server will not route game data between the server and the client, though.)

With the help of the meta-server, we have more techniques to try (in order):

  1. The client tries to connect to the server normally, as in local connexions. It fails if the server cannot be reached through a firewall or router. On the server, use "TCP game server port" to fix a specific port that you can let in.
  2. The client (through the meta-server) asks the server to try to connect backwards to the client. This fails if the client cannot be reached through a firewall or router. On the client, use "Client incoming TCP port" to fix a specific port that you can let in.
  3. They try to connect to each other using a technique known as simultaneous SYN exchanges. In some cases it works even if both the client and the server are behind a firewall. This is not a way to hack through firewalls and break the security of a network, it is a perfectly official (if rarely used) way to connect two machines and it only works if the two machines are willing to actively connect to each other in the first place.



You can e-mail any question or trouble to me, arigo, at users.sourceforge.net, or join our IRC channel #ima on irc.freenode.net.

Please don't hesitate to contact me. As Bub & Bros interacts with an external web browser to run, there are probably configurations that will break it. It has been tested on Windows ME, MacOS X and Linux PCs, but this is no guarantee that it will always work -- far from it.



Armin Rigo and the IMA connection

The Bub's Brothers Home page