InSim

InSim is a protocol which allows an external program to communicate with Live for Speed. It allows you to create a socket connection with the game and to send and receive packets of data. The InSim protocol describes how each of these packets is formatted, and any programming language which can create a network connection and send and receive strings of binary data can interface with it.

The official documentation is included in the file InSim.txt, found in the games docs folder. It consists of a C++ header file that contains the definition for each packet, as well as comments from Scawen as to how each should be used. The documentation here is intended as an ancillary to this file.

UDP vs TCP

InSim supports both UDP and TCP connections. In UDP mode only a single connection can be made, however up to eight connections can be made to the game in TCP. Whether connected in TCP or UDP, it's possible to specify a separate UDP socket for receiving car position updates, such as IS_MCI and IS_NLP.

InSim libraries

Of course as the old adage goes you shouldn't try to reinvent the wheel (unless you're trying to learn more about wheels) and there are several mature InSim libraries available for use in your own code.

InSim Libraries
Library	Platform	License	Webpage / repo / download
LFSLib	.NET Framework	GPL	Project page
LFS_External	.NET Framework	Freeware	LFS Forum
JInSim	Java	Mozilla	LFS Forum
pyinsim	Python	LGPL	LFS Forum
CInSim	C/C++	Freeware	LFS Forum
phplfs	PHP5	Apache License V2.0	Project page
PRISM	PHP7	MIT	LFS Forum
InSim.NET	.NET Framework	LGPL	LFS Forum
insim.rs	Rust	MIT	GitHub, Documentation, Crates.io, LFS Forum
PIE	PHP7	Freeware	LFS Forum
Node InSim	Node.js	MIT	LFS Forum, GitHub, NPM
ktinsim	Kotlin	MIT	LFS Forum, GitHub
Godot InSim	Godot	MIT	LFS Forum, GitLab

InSim reference

The following is a complete list of available InSim packets, as of LFS 0.8B (InSim version 10).

Packet Reference
Packet	Description	Type
Initialisation
IS_ISI	InSim initialisation	Instruction
Version Information
IS_VER	Version information	Info
General Purpose
IS_TINY	General purpose 4-byte packet (no data)	Both
IS_SMALL	General purpose 8-byte packet (4-byte value)	Both
IS_TTC	General purpose 8-byte packet (UCID + three 1-byte values)	Instruction
State Reporting and Requests
IS_STA	Sent when the game state changes	Info
IS_SFP	Send to set various game states	Instruction
IS_ISM	Sent when a host is started or joined	Info
Text Messages and Key Presses
IS_SCH	Send a single character or key press	Instruction
IS_MSO	Text messages sent by the game	Info
IS_III	User message sent to host InSim	Info
IS_MST	Send a message or command to LFS	Instruction
IS_MTC	Send a message to a connection or player	Instruction
IS_MSX	Send a message (longer than IS_MST)	Instruction
IS_MSL	Send a message to the local game client	Instruction
Voting
IS_VTN	Notification for player votes (restart race, qualify, etc.)	Info
Race Tracking
IS_RST	Session information	Info
IS_REO	Grid order (info or instruction)	Both
Autocross
IS_AXI	Autocross layout information	Info
IS_AXO	Autocross object hit	Info
IS_UCO	InSim checkpoint/circle report	Info
IS_OCO	Object control	Instruction
IS_AXM	Autocross info for multiple objects	Both
Connection Tracking
IS_NCN	New connection joined the server	Info
IS_CNL	Connection left the server	Info
IS_CPR	Player changed name	Info
IS_ACR	Admin command report	Info
IS_NCI	New connection with extra info (for host)	Info
IS_SLC	Connection selected a car	Info
IS_CIM	Connection's interface mode changed	Info
Car Tracking
IS_NPL	Player joining the race or leaving pits	Info
IS_PLP	Player pitted (garage screen)	Info
IS_PLL	Player left (spectated or removed from the race)	Info
IS_LAP	Lap completed	Info
IS_SPX	Split line crossed	Info
IS_PIT	Pit stop information	Info
IS_PSF	Pit stop finished	Info
IS_PLA	Car entered or left the pit lane	Info
IS_PEN	Penalty given or cleared	Info
IS_TOC	Driver swap	Info
IS_FLG	Player shown flag	Info
IS_PFL	Player flags changed (help/settings flags)	Info
IS_FIN	Player finished the race	Info
IS_RES	Player result confirmed	Info
IS_NLP	Player's current position, lap, and node information	Info
IS_MCI	Car info for multiple cars (more detailed than IS_NLP)	Info
IS_CRS	Car reset	Info
IS_CON	Collision report for contact between cars	Info
IS_OBH	Collision report for contact between a car and an object	Info
IS_HLV	Hotlap validity violation report	Info
IS_CSC	Car state changed	Info
Camera Control
IS_SCC	Set car camera	Instruction
IS_CPP	Set the camera position, or receive the current camera position	Both
Replay Control
IS_RIP	Load and/or set replay position, or get replay information	Both
Screenshots
IS_SSH	Take a screenshot, or get a screenshot report	Both
InSim Buttons
IS_BFN	Delete InSim buttons, or receive button requests	Both
IS_BTN	Shows a button on a local or remote screen	Instruction
IS_BTC	Sent when a user clicks a button	Info
IS_BTT	Sent after typing text into a button	Info
AI Control
IS_AIC	Set AI control value	Instruction
IS_AII	Info about AI car	Info
Other packets
IS_MOD	Set screen mode	Instruction
IS_CCH	Camera changed	Info
IS_PLC	Sets a player's allowed cars	Instruction
IS_HCP	Sets car handicaps	Instruction
IS_JRR	Approve/reject player joining, spawn/reset/teleport car	Instruction
IS_MAL	Sets allowed mods on the current host	Both
IS_PLH	Sets player handicaps	Both
IS_IPB	Sets IP bans	Both

You can also reference the InSim enumerations and InSim structs used in the various packets.

InSim examples

How you go about creating an InSim connection is of course dependent on which programming language you are using, but here we make an attempt to document the process with some examples from the popular Python programming language. As mentioned above any language capable of making a socket connection can be used to interface with LFS, however the principle remain the same regardless.

Creating a connection

First of all we must establish a socket connection with the game, in this case in TCP.

# Import Python's socket module.
import socket

# Initialise the socket in TCP mode. 
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

# Connect to LFS.
sock.connect(('localhost', 29999))

Initialising InSim

After establishing the connection we must initialise the InSim system by sending the IS_ISI packet. Before we can do this however we must first intitailse InSim within LFS itself. To do this start the game and enter the chat command /insim 29999. The port number used can be any valid port, but 29999 generally tends to be the accepted default.

Here is the definition for the IS_ISI packet from InSim.txt.

struct IS_ISI // InSim Init - packet to initialise the InSim system
{
	byte	Size;		// 44
	byte	Type;		// ISP_ISI
	byte	ReqI;		// If non-zero LFS will send an IS_VER packet
	byte	Zero;		// 0

	word	UDPPort;	// Port for UDP replies from LFS (0 to 65535)
	word	Flags;		// Bit flags for options (see below)

	byte	Sp0;		// 0
	byte	Prefix;		// Special host message prefix character
	word	Interval;	// Time in ms between NLP or MCI (0 = none)

	char	Admin[16];	// Admin password (if set in LFS)
	char	IName[16];	// A short name for your program
};

Each InSim packet begins with a header, consisting of 4 bytes. The first byte is the size of the packet, followed by the packet type from the ISP_ enumeration, and then the ReqI (standing for Request Id). Whenever a request is made to LFS the value of the ReqI must be set to non-zero, whereby LFS will reply with the same value set in the ReqI of the requested packet. Finally the fourth byte varies depending on the type of packet in question, which in this case is blank.

As you can see the IS_ISI packet contains various options and flags that are used when initialising the InSim system. We must pack this data into a binary formatted string to send it to LFS.

# Import Python's struct module, which allows us to pack and unpack strings.
import struct

# Pack the IS_ISI data into a string.
isi = struct.pack('BBBBHHBcH16s16s', 
                  44,           # Size
                  1,            # Type
                  1,            # ReqI
                  0,            # Zero
                  0,            # UDPPort
                  0,            # Flags
                  0,            # Sp0
                  ' ',          # Prefix
                  0,            # Interval
                  'password',   # Admin
                  'MyProgram',) # IName

# Send the string to InSim
sock.send(isi)

Receiving Data

After creating the connection and initialising InSim we must then setup the packet receive loop. As data in TCP mode is sent as a constant stream of data, multiple packets may arrive in a single receive call and some packets may arrive incomplete. This means we must store all incoming data in a buffer and then read each packet out when we are sure it is complete.

# We use a string as the buffer.
buffer = ''

while True:
    # Receive up to 1024 bytes of data.
    data = sock.recv(1024)

    # If no data is received the connection has closed.
    if data:
        # Append received data onto the buffer.
        buffer += data

        # Loop through each completed packet in the buffer. The first byte of
        # each packet is the packet size, so check that the length of the
        # buffer is at least the size of the first packet. 
        while len(buffer) > 0 and len(buffer) > ord(buffer[0]):
            # Copy the packet from the buffer.
            packet = buffer[:ord(buffer[0])]

            # Remove the packet from the buffer.
            buffer = buffer[ord(buffer[0]):]

            # The packet is now complete! :)
            # doSomethingWithPacket(packet)
    else: 
        break

# Release the socket.
sock.close()

Unpacking Packets

Once we have received the packet data as a binary formatted string, we then have to unpack this data into a format which is useful to us. In our previous example when we sent the IS_ISI initailisation packet, we set the ReqI to non-zero, meaning that LFS responded with an IS_VER version packet, however we didn't do anything with it. Firstly lets look at the definition for the IS_VER packet from InSim.txt.

struct IS_VER // VERsion
{
	byte	Size;			// 20
	byte	Type;			// ISP_VERSION
	byte	ReqI;			// ReqI as received in the request packet
	byte	Zero;

	char	Version[8];		// LFS version, e.g. 0.3G
	char	Product[6];		// Product : DEMO or S1
	word	InSimVer;		// InSim Version : increased when InSim packets change
};

Now lets look at how we would unpack that data in Python.

# Import Python's struct module.
import struct

# Unpack the binary formatted packet data into the values we need.
size, type, reqi, zero, version, product, insimver = struct.unpack('BBBB8s6sH', packet)

# Check the InSim version.
if insimver != 4:
    print 'Invalid InSim version!'
    sock.close()

Keep Alive

In order to keep the connection open LFS will send a "keep alive" packet every 30 or so seconds. This packet is an IS_TINY with a SubT (sub-type) of TINY_NONE. We must respond to this packet every time it is received in order to prevent the connection with InSim from timing-out.

# Some constants.
ISP_TINY = 3
TINY_NONE = 0

# Check the packet type.
if ord(packet[1]) == ISP_TINY:
    # Unpack the packet data.
    tiny = struct.unpack('BBBB', packet)
    # Check the SubT.
    if tiny[3] == TINY_NONE:
       # Send the keep alive packet back to LFS.
       sock.send(packet)

Further examples

You can see the full example of this code as well as others on the InSim examples page.