JKG Server Guide (Phase I)

A great way to help participate with the Jedi Knight Galaxies (JKG) community and have fun with your friends is by hosting a server. JKG can be hosted on a Linux or Window's server. We recommend Linux, as it is probably the cheapest and easiest to maintain option. This tutorial will assume you are hosting the device in question on a regular ipv4 DHCP or static address. As a general reminder when it comes to server security, be sure to make passwords (such as rcon or admin account passwords) at least 16 characters in length and randomly generated and unique to each account/username. The default passwords configured by JKG's initial configuration are intended to be temporary examples, and SHOULD NOT be used on real servers. Be sure to keep the operating system on your server up to date and patched. JKG works great as either a LAN server or an internet facing public server, a ping no greater than 200 is recommended, but the game can still be played with higher latency. There are a variety of locations available online that can help provide resources to host a server on (such as Asutech), or you can host it from the comfort of your own home. JKG make use of UDP packets to send/receive information.

Server Naming

It is recommended you include the server's general location in it's name (eg: NA, EU, AUS, JAP, etc), as player's are often organized by regions and interested in playing with player's with similar pings. You can find a list of current internet servers here. While you are free to include the server's gameversion in the server's name, as of v1.3.23 (and later versions) this information is now contained within the serverinfo broadcast information and displays in the client's UI.

Phase and Version Information

JKG generally has two public versions available (though this is not always the case): the primary/stable version and the test/beta version. It is recommended that those wishing to host the latest version (test/beta), be prepared for some instability and more frequent updates. JKG's versioning system includes an optional letter at the end of the version string (eg: v.1.3.22a), this is used for emergency server-side only fixes. Client's with the same version number, but with a different or no letter can still join servers hosting a newer version without the letter. If a client tries to join a server with a different version string (eg: v1.3.22c tries to join v1.3.23), they will receive a message indicating they need to update their client. Please note that as JKG's development continues to work towards the phase system release, we eventually plan on providing a way for server hosts to enlist to become 'Official' servers. Official server's hosted by 3rd parties, need to follow a much more stringent configuration and rules, but we also plan on allowing unofficial server hosts to continue hosting their own customized variants of the game that do not adhere to these rules. This information is subject to change, but we hope this will continue to be possible during later phase releases.
 

Setup

First install JKG. You can download the game and find instructions for installing on the website. The game is about 600MB in size in addition to Jedi Academy. JKG's server supports some multithreading (mainly for scripting lua, usually no more than 4 is useful), but is primarily a single threaded application so will generally scale better with faster clockspeed and storage read/write speeds than additional processors. Running the server does not require a gpu, (except for displaying console text to the screen of the hosting machine).

Lua Admin Accounts

Once you have installed the game, you're going to want to setup an admin account for the ingame lua system. You can find a list of these accounts within /JKG/server/accountlist.json. A list of the permissions these accounts have can be found in the same directory /JKG/server/ranks.json.
 

Server.cfg

Next we'll want to setup the server's configuration file. This can be found in /JKG/server.cfg. There are a number of settings we'll likely want to change in this file to suit your needs. We'll go over the most important, but you can specify any of the game's cvar's you want your server to use from this file. server.cfg will look like this:

/////////////////////////////////////////////
//
// Jedi Knight Galaxies - Server config
//
/////////////////////////////////////////////

// --==-- Rcon --==--
set rconPassword ""

Here's the first most important setting, the rconPassword. If you want to enable rcon on your server, just put your password inbetween the quotes. You can use the rcon command to remotely issue commands to your server after setting this up. For example if my rconPassword was passwordExample, if I wanted to change the server's current map from a client, I could connect to the server and then open the console and type in the following:

rconpassword passwordExample
rcon map jkg_ctf_bespin

And the server would change the map to Bespin. Keep your rconPassword secure and do not share it. If you do not want to enable rcon, then you can just leave the rconPassword set to nothing ( "" ). Let's move onto the next setting section.

// --==-- General information --==--
set sv_hostname "Put Your Server Name Here" 
set g_motd "Put your Message Of The Day Here." //currently unavailable in jkg
set sv_pure "0" //whether clients connecting are required to have identical assets to the server or not
set sv_fps "40" 
set sv_maxRate 11000
set sv_timeout 800
set sv_allowDownload "0" // Do not set to 1
set sv_floodProtect "0" // We don't need this primitive flood protection

• sv_hostname let's us set the name of your server to what you'd like. The default name is 'Put your Server Name Here'. Some other important settings are also covered here.
• g_motd sets the server's message of the day, which is displayed to clients upon joining. Note this feature is currently disabled in JKG.
• sv_pure determines if clients are not allowed to use mods such as skins while playing, if set to 1, they must have identical assets to the server to join.
• sv_fps sets the frame rate of the server (not client), the default is 40 and we don't recommend using other variables.
• sv_maxRate is the maximum rate of data allowed to be sent in frames, higher is generally better (eg: 40000), but can cause lag and other issues on clients that have a poor connection, but generally makes for a smoother gameplay experience for clients that can handle it. If you want to accommodate player's with poor quality connections, low bandwidth and high ping, we recommend a lower setting (eg: 10000). LAN server's should probably use the highest setting possible.
• sv_timeout is how high a ping a client is allowed to have before they are timed out.

JKG should not use sv_allowDownload or sv_floodProtect so these are disabled by default.

set jkg_name "JKG Server" // Server name to use when registering
set jkg_dialcode "jkgofi#" // Stargate address to this server (6 alphanumeric characters followed by a #, each character can only be present once)
set jkg_serverid "NewJKGServer" // Unique identifier for this server, 16 characters max, alphanumeric
set jkg_url "" // If applicable, the URL to use to connect to your server (port excluded), if left empty, your external IP will be used

These settings do not really affect Phase I servers, but will eventually be used in later phases. jkg_name is a distinct name sent to the master server, but not displayed to clients. The other settings here are not currently used, except jkg_url which can be used to associate the server's ip address with a domain name.

// --==-- Anti-Q3Fill/Non-JKG client settings --==--
set jkg_antifakeplayer 1	// Enable fake player protection

// --==-- Server Settings --==-- 
set fraglimit "50"
set timelimit "45"
set bot_minplayers "0"   //how many minimum number of bots should spawn when there are available slots on teams
set duel_fraglimit "10"    //For Duel, the number of rounds to win the map\game 
set capturelimit "10"   // number of flag captures to win and end a CTF game before time runs out

jkg_antifakeplayer is a security setting to prevent some exploits which should be enabled. The other settings here change the server's game variables. For example fraglimit changes how many kills are required before a match ends.

// --==-- JKG Faction Battle Settings --==--
set jkg_startingCredits "500"  //how many credits each player starts with upon joining a team
set jkg_creditsPerKill "150"   // how many credits are paid out for a kill
set jkg_shop_replenish_time "300"  //how often the vendors refresh their wares (in seconds)
set jkg_bounty "225"  //how much is paid out for a bounty (gets multiplied for successive bounties)
set jkg_allowDodge "1"  //whether or not player's can use roll to 'dodge' damage

Here we have more settings specific to JKG. There are many settings that can be changed here and not listed in the server.cfg most of these can be found in g_xcvar.h of the code, but the defaults are recommended. For example, jkg_underdogBonus if set to 1 will give bonus credits to player's who join the match late and adjust it based on which team is losing. The other settings listed in the .cfg are the most commonly used that server owner's might want to adjust. We recommend looking through the rest and changing it to suit your preferences. The default .cfg contains a customized map cycle for your use, but feel free to make your own or add additional maps your server will be using. When you're done save the server.cfg.

Congrats you're almost ready to host your server.
 

Hosting a LAN Server

We recommend trying this first before hosting a public internet server to give you a feel for things. A LAN server is one that works only within the local area network, also sometimes referred to as the local intranet. Only the devices connected to the network the server is on will be able to see and interact with the server. To start up your dedicated server open up a terminal/cli and navigate to the directory JKG is installed at. Inside of the jkgalaxies directory where JKG is installed, you should usually have the following files:

Linux

 |  |---- jkgalaxies
 |  |  | --- JKG (sub directory)
 |  |  |
 |  |  |--- JKGalaxies-Changelog.txt 
 |  |  |--- jkgalaxies.x86_64
 |  |  |--- jkgalaxiesded.x86_64
 |  |  |--- rd-galaxies_x86_64.so
 |  |  |--- runJKGalaxies.sh
 |  |  |--- runServer.sh

Use a text editor (such as vim) to edit runServer.sh it should look like the following:

#!/bin/sh
#this is for a local LAN server
./jkgalaxiesded.x86_64 +set fs_game "JKG" +set fs_cdpath "." +set fs_basepath ".." +set dedicated 1 +exec server.cfg

#this is for a dedicated server (don't forget to setup port forwarding)
#./jkgalaxiesded.x86_64 +set fs_game "JKG" +set fs_cdpath "." +set fs_basepath ".." +set dedicated 2 +set net_port 29070 +exec server.cfg

As you can see the two are quite similar, we want to use the first one to host a LAN server, comments are denoted with a line starting with a # so you can add or remove a comment to switch between an internet server or a LAN server.

Hosting an Internet Server

As you can see from the above LAN example, we can use the same .sh or .bat script file to launch an internet server instead of a LAN one (just use the 2nd line instead). There is however one other thing we need to do. You'll need to set your home network's router to allow port forwarding (sometimes also called port mapping or port triggering). This essentially tells your router to forward incoming and outgoing traffic on the JKG port (by default that's port 29070 or whatever you specified in your runServer script), through your firewall to the relevant machine on the local network. There is no standardized interface for routers so they all vary a little bit, but you can usually look up instructions for your router on this site. JKG uses UDP traffic (not TCP - some routers will ask you to specify which type). Once you've saved the settings it usually takes about one minute to begin actually forwarding the relevant traffic. Make sure you've also configured the server's OS to allow the traffic for that executable through the firewall. Be aware some ISPs also prevent you from doing this, and you may need to also check with them to make sure they allow port forwarding. If your router asks if it should forward both internal and external traffic for the port, allow both.

Once you've setup your port forwarding on your router, save the changes and logout of your router. Go ahead and launch your server's runServer.sh or runServer.bat script and it will start your server. After a minute or so your servers should send heartbeat packets to the master server(s). You can test that your server is online, by checking the Online Server List. If it shows up there, it's working. You could also test it by having a friend on a different network connection try to join your server.

Recommendations

Scripts

Because software sometimes crashes due to undiscovered bugs, its probably a good idea to setup a restart script for your runServer script (or make the script a service). This way if the jkgalaxiesded.x86 executable crashes, you can have the server reboot on its own.

Linux

For example, on Linux with a bash script you could do the following:

#!/bin/bash

until ./runServer.sh; do
    echo "Server crashed with exit code $?.  Restarting..." >&2
    sleep 1
done

This script will restart everytime the server crashes, but not restart if the server is shutdown normally (the executable returns a 0).

If you want to have it restart everytime even if the server receives a shutdown command, you could change it to this instead:

#!/bin/bash

while true; do
    ./runServer.sh
    echo "Server stopped (exit code: $?).  Restarting..." >&2
    sleep 1
done

Windows

The windows equivalent would be something like this:

::restart server
@echo off
:loop
./runServer.bat
TIMEOUT /T 1
GOTO:loop

However, we would recommend you use a service on Windows as this will provide a lot more flexibility.

RCON Suggestions

You can find other helpful combinations and suggestions for using rcon commands at this tutorial (applies to Jedi Academy, but is mostly the same).  If you need help generating a random RCON password, you can use Didz's generator here.

Common Errors

"When people try to join, they get 'Awaiting Connection...` with the number of seconds they've been waiting"?
Usually this means the server cannot be reached by the client if more than a few seconds go by. The server most likely has configured something incorrectly, such as their port forwarding.

"When people join their weapon keeps automatically swapping and can't fire."
This usually happens if the client's asset5.pk3 contents mismatches with the server's. Usually the client needs to update to the correct asset5.pk3 or the server could also be hosting out of date files.

"The game tells me to update my clientside when I try to join a server."
This message means that the version of the game you are playing on is not the same as the server's you are attempting to connect to.  This can mean that the server you're trying to join is using an older version, or it can mean yours is out of date.  Most commonly this happens because the server is hosting a new beta and you are using the most recent stable release rather than the beta.  Keep in mind that the download page for JKG has two different versions on it a stable release, and a beta/test release.  These are generally not compatible.  You can check to see which version you are currently using by opening the console (~), and typing in `gameversion` to get the version string of your client, or `version` to get a very specific git build commit (usually this is not necessary unless you compiled the game yourself).  For example: