InSim Tutorials

Information

The Tutorials section is meant to become a collection of tutorials on how to connect to InSim using various programming languages. I know that of course there are lots of precompiled software packages (like JInSim for Java, FullMotion.LiveForSpeed for C# and so on) on the LfSForum and lots of them are also very good, but you do not really learn how to use InSim if you use precompiled packages. So each section of this page should be for one programming language and should contain the following subsections:

1. Datatypes
2. How to build/parse packets
3. Connecting to InSim
4. Disconnecting from InSim
5. Easy example

Tutorials

Tutorials are available for the following programming languages:

PHP5

InSim Relay usage information

The InSim Relay is a service that can connect to your LFS host via InSim and relay the InSim information sent by your host, to anyone who connects to the InSim Relay. This relayed data can be used by programmers for various things, such as the LFS Spectator (remote viewing of a race) and race-tracking to store race information and statistics.

To have your host connected to the Relay, see this page on LFS World: http://www.lfsworld.net/?win=hosts&whichTab=insim_relay

The rest of this document is only for programmers who want to know how to connect with the InSim Relay, so they can make use of the available data.

NEW : you can now also connect various other insim mods via the relay, because you can 'connect' to a host with an admin password. See the bottom of this document for which packets are allowed to send.

Connecting to the InSim Relay

The network protocol used with the Relay is UDP and it is located at isrelay.liveforspeed.net port 47474

Connecting to the Relay is done with the CCN packet. To connect, make sure bit 0 of the flags is set, which means 'connect to relay'. The CCN packet is a multifunctional packet. It is used to connect to the Relay, request a list of available hosts and set various options.
Here is the struct of the connection packet:

struct ClientConnection
{
	char	Id	[4];	// CCN + zero (\0)
	byte	Flags;		// Bit flags for options and 'connect' flag
	byte	Spare;		// spare1
	byte	Spare;		// spare2
	byte	Spare;		// spare2
}

Flags in CCN packet:
#define ISR_CONNECT	1	// bit 0 : 'connect' flag. Must be set to connect to Relay
#define ISR_HOSTLIST	2	// bit 1 : if set, you will get a list of hosts returned
#define ISR_NOMCI	4	// bit 2 : if set, you will not receive MCI packets
#define ISR_VERIFY	8	// bit 3 : if set, 'guaranteed delivery' will be on

The CCN packet with bit 0 set _must_ be your first packet, otherwise your packets will be ignored. To acknowledge that the connection was successful, an ACK packet is sent, if you didn't already request a hostlist in your initial CCN packet.
You can additionally send a CCN packet at any time, to toggle NOMCI and/or VERIFY and to request a hostlist even while still being connected to a host.
A note about guaranteed delivery; it works exactly like with normal InSim guaranteed delivery, so if you don't know how it works, please look in the Insim.txt that comes with LFS.

There is one official case where connecting might fail; when the Relay has reached its maximum number of users.

In that case, the Relay will send an ERR packet. The ERR packet also has some other error message purposes.

struct ErrorMessage
{
	char	Id	[4];	// ERR + zero
	byte	ErrNo;		// number of the error
	byte	Spare;		// spare1
	byte	Spare;		// spare2
	byte	Spare;		// spare2
}

ErrNo meanings:
1 - Invalid Spectatorpassword given
2 - Relay has reached maximum number of clients
3 - Non-existent hostname given in HOS packet

Receiving the hostlist

When you have requested a list of hosts with bit 1 of the flags in the CCN packet, you will receive a list of hosts. The result packet(s) is/are identified by the CHL id. Every CHL packet contains a maximum of 8 hosts and their respective information. If there are more than 8 hosts available to select from, you will receive multiple CHL packets. You can determine how many CHL packets you should expect by reading the 'total hosts' word in every CHL packet (this number is the same in every CHL packet). You can determine the amount of hosts listed in a CHL packet, by the length of the packet.

struct ClientgetHostList
{
	char	Id	[4];	// CHL + zero
	word	NrHosts;	// Number of total available hosts
	byte	Spare;		// Spare1
	byte	Spare;		// Spare2
	char	Host	[32];	// Hostname(s) (min: 1 / max 8 hostnames - check the length of this packet)
	byte	NrRacers;	// Number of racers on a host
	byte	Specpass;	// 1 if host requires a spectator password
}

An example of the order things in this packet:
3 hosts listed in this packet:

host1[32].host2[32].host3[32].421110

host1 has 4 racers and requires a specpass
host2 has 2 racers and required a specpass
host3 has 1 racer and does not require a specpass

Select a host to receive InSim data from

To start receiving InSim packets from a host, you must select the host with a HOS packet:

struct SelectHost
{
	char	Id	[4];	// HOS + zero
	char	Host	[32];	// hostname
	char	Specpass[24];	// spectator password
	char	Adminpass[16];  // admin password
}

Note that both the full hostname and ^-stripped/converted hostname can be used.

ex. "^1EXAMPLE^v^7HOST ^11" or "EXAMPLE|HOST 1"

Maintaining a connection to the Relay

If the relay has not received any data from a client in 60 seconds, the Relay will close the connection with the client. To prevent this from happening, the client can send ACK packets every 20 seconds, in case nothing else has been sent to the Relay.

struct Acknowledge
{
	char	Id	[4];	// ACK + zero
}

If you need to, you can optionally add 4 null bytes, but it's not required for the relay to recognise the ACK packet.

The same goes for the other way around. The Relay will send ACK packets to your client in case nothing has been sent in 20 seconds. You can make your client assume that the Relay is offline, if you didn't receive anything from the relay during 60 seconds.

Closing a connection (client side)

When the client closes, it's nice to have it send a 'close' instruction to the Relay:

struct ClientClose
{
	char	Id	[4];	// ISC + zero
}

If you need to, you can optionally add 4 null bytes, but it's not required for the relay to recognise the ISC packet.

Closing a connection (relay side)

If the relay needs to "close" your connection for whatever reason or if the relay goes offline, it will send a packet to notify that you will need to try to connect again with the CCN packet.

struct ClientTerminate
{
	char	Id	[4];	// CTM + zero
}

Public requests for host information

A client can request some information from a host by sending the relay one of the following InSim packets:

SST
ISM
VER
GTH
NPL
RES

These packets are regular InSim packets, so for their structs, please see the insim.txt file included with every distribution of S2 or the S2 dedicated host.

Admin-only control packets

If you have connected to a host with the adminpassword set (in the HOS packet), you are allowed to send some control packets:

VTC

SCH
MST
MTC

These packets are regular InSim packets, so for their structs, please see the insim.txt file included with every distribution of S2 or the S2 dedicated host.

List of escape codes

^v - |
^a - *
^c - :
^d - \
^s - /
^q - ?
^t - "
^l - <
^r - >

^L = Latin 1
^G = Greek
^C = Cyrillic
^J = Japanese
^E = Central Europe
^T = Turkish
^B = Baltic

^0 - Black
^1 - Red
^2 - Light green
^3 - Yellow
^4 - Blue
^5 - Purple
^6 - Light blue
^7 - White
^8 - Dark green (default)