gcb 1.0.2-dev
-------------

gcb (formerly Garena Client Broadcast) facilitates connections between Garena clients and a Warcraft III server (theoretically, it should be possible to configure other games by altering certain configuration options, but this has not been tested).

First, gcb listens to broadcasts to UDP port 6112, and then forwards these game broadcasts via Garena's encapsulated UDP protocol. Then, eventually a user should join the game; gcb will receive a TCP connection request over Garena's virtual TCP protocol, and will begin relaying packets between the Garena client and a Warcraft III server (the server hostname and port are preset; multiple connection ports can be specified). Note that any Warcraft III server over LAN can be used, including GHost (and, of course, normal Warcraft III LAN hosting).

gcb_bot is a chat bot for Garena. See README_BOT for details on this. The source code for both gcb and gcb_bot are in the same package. The activition of gcb_bot requires a change in gcb.cfg. The remainded of this document will focus on gcb; requirements, installation, configuration, and parts of running also apply to gcb_bot, however.

REVERSE is a tool that allows you to use gcb to connect to remote Garena client hosts on Garena-unsupported systems.

Requirements
------------

JRE >= 5.0.
bouncycastle library for RSA
MySQL Connector/J
Apache Commons Configuration
Java(TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

bouncycastle can be downloaded at http://www.bouncycastle.org/latest_releases.html. The specific JAR file you need is "bcprov-jdk15-146.jar".

MySQL Connector/J can be downloaded at http://www.mysql.com/downloads/connector/j/.

Apache Commons Configuration can be downloaded at http://commons.apache.org/configuration/.

Note that the above libraries are now included with gcb, so there is no need to download them. You can find the JAR files in gcb/bin/lib/; if you plan to move gcb.jar away from it's directory, make sure you move the lib/ folder as well because gcb will fail without it.

Before running, you do need to install the Java(TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6. This can be downloaded at http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html (unfortunately, it is not free software; if you are concerned about this, try gcj or OpenJDK). The download will include installation instructions that you should follow.

The JRE can be downloaded at http://www.java.com/en/download/index.jsp.

Installation
------------

Installation only consists of unzipping the ZIP file and making sure you have the requirements (particularly the cryptography extension). The latest version may be downloaded from http://code.google.com/p/gcb/. Alternatively, you can run the following command to check out the latest SVN:

svn checkout http://gcb.googlecode.com/svn/trunk/ gcb-read-only

Configuration
-------------

Most variables that may need to be configured can be configured in gcb.cfg. See that file, bin/gcb.cfg, for deatils; each key should have a short description of how to determine it's appropriate value.

The keys that you need to set are: garena_username, your Garena username; garena_password, your Garena password; garena1_roomname, the name of the room that you want to join (alternative, set garena1_roomid, the ID of the room you wish to join, and garena1_roomhost, the hostname of the room you wish to join; if you set the name of the room, these values are autodetected).

Running
-------

To run gcb, you should only have to execute the JAR file under JVM:

java -jar gcb.jar

Note that you can simply double click on the gcb.jar file; however, in this case, gcb will run exclusively in background and a console will not open with log data. Also, you should not run gcb with root pemissions!

You can also specify a configuration file for gcb to use. This allows you to theoretically use one JAR file for multiple bots (but as you'll see later this can't actually be done; and there's no point anyway). The default configuration file is gcb.cfg.

java -jar gcb.jar myconfigfile.cfg

Port 6112 UDP must be available, because gcb listens for Warcraft III game broadcasts on that port. Port 1513 UDP must also be available, because gcb sends and receives GP2PP messages on that port. Thus, you can only run one instance of gcb on a machine.

gkey.pem contains the private RSA key that all Garena clients use. It should be updated in the event that Garena uses another key (although this is not likely). Note that this means Garena's encryption can easily be broken, and the password hash can be retrieved; this is not an issue with gcb.

Plugins
-------

To install a plugin, download the plugin ZIP file and then unzip in gcb/bin/plugins/. The plugin can then be loaded via !loadplugin <pluginname>. Note that a restart is required so that gcb can find the plugins (this may be changed in a later release).

You can automatically load specific plugins at startup. From the plugin configuration file (for example: example.plugin.cfg or example.gcbp.cfg), take the classname; include this classname in the configuration key gcb_plugins in gcb.cfg.

WARNING: plugins are not sandboxed; they can do whatever they want. If you do not trust a plugin, then DON'T install it!

-------------------------------------------------------------------------------
Compilation
---------

To compile gcb, you need JDK >= 5.0. This can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html. Compilation of gcb has not been tested with GNU's gcj, but it should work.

To compile:

javac -classpath "src/:bin/lib/*" src/gcb/Main.java

Note that on Windows, the Linux ':' path separator should be replaced by ';'.

ID from RoomEN.dat
------------------
RoomEN.dat in your Garena installation is actually an sqlite database. This can be opened with an sqlite client, such as the Firefox SQLite Manager, available at https://addons.mozilla.org/en-US/firefox/addon/sqlite-manager/.

To retrieve the ID, you can either manually use an sqlite client like the one above, or you can use gcb_list. Instruction for gcb_list are available at gcb_list/README. To manually retrieve:

The Room ID and Server ID can be found by searching the table named "RoomTab". For example:

SELECT RoomID, ServerId FROM RoomTab WHERE RoomName=' WC3 ROC USA Room'

Note the space preceeding the room name. The Room ID should be recorded as "gcb_roomid".

To find the Room IP address, execute:

SELECT IP FROM RoomServerTab WHERE ServerId=<server_id>

Were <server_id> is the Server ID you found earlier.

The IP address is stored as an integer. It can be converted into an actual address: it is the integer representation of the IP address stored in little endian. This tool may help you: http://www.silisoftware.com/tools/ipconverter.php. To use it with the integer from the SQLite database, type the integer in for "Integer IP". You will receive the four parts under "Decimal IP". Reverse these parts (1.2.3.4 -> 4.3.2.1) to retrieve the original IP address.

Set "gcb_roomhost" to the original IP address.

Creating plugins
----------------

Plugins are relatively powerful as they have access to packets and commands from users, among other things. A guide for creating your own plugins is available at: http://code.google.com/p/gcb/wiki/CreatingPlugins. You may also wish to look at the included gcb example plugins.

GCBI Protocol
-------------

gcb can send data on the joining user to GHost++ through GCBI. gcbi.patch should be included in your installation. Apply this patch on GHost++, and then in gcb.cfg, configure gcb_enablegcbi to true.

The patch only prints out the information. Because there are different uses for the information, further modification of GHost++ must be done for there to be a purpose. The information sent includes: the user ID, the room ID, the user's actual IP address, the user's Garena country code, the user's Garena experience.

gcbi_extend.patch also sets the external IP string of each player to their actual IP address from Garena, so that bans should work.

Also note that if GCBI is enabled without applying the gcbi patch to GHost++, gcb will be disconnected and not allowed to join games.

Protocol
--------

Much of the code is based off of the included garena_protocol.txt. This was not created by me, and was essential to the creation of this client. Note that some details inside the text file are outdated. For example:

version identifier at the time this document was created: 0x0000027C
GSP session login packet is a bit different: a byte with value 1 precedes the internal IP address and there seem to be two bytes after the internal IP address, I don't know what they are for.

There may be other differences. See gcb source code for more information.