InSim for Live for Speed

0.5Z

InSim allows communication between up to 8 external programs and LFS.

TCP or UDP packets can be sent in both directions, LFS reporting various things about its state, and the external program requesting info and controlling LFS with special packets, text commands or keypresses.

Content

CHANGES

0.5Z

compatible so no change to INSIM_VERSION
NLP / MCI packets are now output at regular intervals
CCI_LAG bit added to the CompCar structure

TYPES

all multi-byte types are PC style - lowest byte first

InSim PACKETS

All InSim packets use a four byte header

INITIALISING InSim

To initialise the InSim system, type into LFS : /insim xxxxx where xxxxx is the TCP and UDP port you want LFS to open.

OR start LFS with the command line option : LFS /insim=xxxxx This will make LFS listen for packets on that TCP and UDP port.

TO START COMMUNICATION

ENUMERATIONS FOR PACKET TYPES

GENERAL PURPOSE PACKETS

IS_TINY (4 bytes) and IS_SMALL (8 bytes)

To avoid defining several packet structures that are exactly the same, and to avoid wasting the ISP_ enumeration,
IS_TINY is used at various times when no additional data other than SubT is required.
IS_SMALL is used when an additional integer is needed.

VERSION REQUEST

It is advisable to request version information as soon as you have connected, to avoid problems when connecting to a host with a later or earlier version. You will be sent a version packet on connection if you set ReqI in the IS_ISI packet.

CLOSING InSim

You can send this IS_TINY to close the InSim connection to your program :

ReqI : 0
SubT : TINY_CLOSE (close this connection)

Another InSimInit packet is then required to start operating again.

You can shut down InSim completely and stop it listening at all by typing /insim=0 into LFS (or send a MsgTypePack to do the same thing).

MAINTAINING THE CONNECTION - IMPORTANT

If InSim does not receive a packet for 70 seconds, it will close your connection. To open it again you would need to send another InSimInit packet.

LFS will send a blank IS_TINY packet like this every 30 seconds :

ReqI : 0
SubT : TINY_NONE (keep alive packet)

You should reply with a blank IS_TINY packet :

ReqI : 0
SubT : TINY_NONE (has no effect other than resetting the timeout)

NOTE :
If you want to request a reply from LFS to check the connection at any time, you can send this IS_TINY :
ReqI : non-zero (returned in the reply)
SubT : TINY_PING (request a TINY_REPLY)
LFS will reply with this IS_TINY :
ReqI : non-zero (as received in the request packet)
SubT : TINY_REPLY (reply to ping)

STATE REPORTING AND REQUESTS

LFS will send a StatePack any time the info in the StatePack changes.

To request a StatePack at any time, send this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_SST (Send STate)

Setting states

These states can be set by a special packet :

Other states must be set by using keypresses or messages (see below)

SCREEN MODE

You can send this packet to LFS to set the screen mode.

TEXT MESSAGES AND KEY PRESSES

You can send 64-byte text messages to LFS as if the user had typed them in. Messages that appear on LFS screen (up to 128 bytes) are reported to the external program. You can also send simulated keypresses to LFS.

MESSAGES OUT (FROM LFS)

MESSAGES IN (TO LFS)

You can send individual key presses to LFS with the IS_SCH packet. For standard keys (e.g. V and H) you should send a capital letter. This does not work with some keys like F keys, arrows or CTRL keys. You can also use IS_MST with the /press /shift /ctrl /alt commands.

MULTIPLAYER NOTIFICATION

LFS will send this packet when a host is started or joined.

On ending or leaving a host, LFS will send this IS_TINY :

ReqI : 0
SubT : TINY_MPE (MultiPlayerEnd)

To request an IS_ISM packet at any time, send this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_ISM (request an IS_ISM)

NOTE :
If LFS is not in multiplayer mode, the host name in the ISM will be empty.

VOTE NOTIFY AND CANCEL

LFS notifies the external program of any votes to restart or qualify

Vote Actions

When a vote is cancelled, LFS sends this IS_TINY

ReqI : 0
SubT : TINY_VTC (VoTe Cancelled)

When a vote is completed, LFS sends this IS_SMALL

ReqI : 0
SubT : SMALL_VTA (VoTe Action)
UVal : action (VOTE_X - Vote Action as defined)

You can instruct LFS host to cancel a vote using an IS_TINY

ReqI : 0
SubT : TINY_VTC (VoTe Cancel)

RACE TRACKING

In LFS there is a list of connections AND a list of players in the race Some packets are related to connections, some players, some both

If you are making a multiplayer InSim program, you must maintain two lists You should use the unique identifier UCID to identify a connection

Each player has a unique identifier PLID from the moment he joins the race, until he leaves. It's not possible for PLID and UCID to be the same thing, for two reasons :

  1. ) there may be more than one player per connection if AI drivers are used
  2. ) a player can swap between connections, in the case of a driver swap (IS_TOC)

When all players are cleared from race (e.g. /clear) LFS sends this IS_TINY

ReqI : 0
SubT : TINY_CLR (CLear Race)

When a race ends (return to game setup screen) LFS sends this IS_TINY

ReqI : 0
SubT : TINY_REN (Race ENd)

The following packets are sent when the relevant events take place :

To request an IS_RST packet at any time, send this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_RST (request an IS_RST)

REOrder - this packet can be sent in either direction

LFS sends one at the start of every race or qualifying session, listing the start order

You can send one to LFS before a race start, to specify the starting order. It may be a good idea to avoid conflict by using /start=fixed (LFS setting). Alternatively, you can leave the LFS setting, but make sure you send your IS_REO AFTER you receive the IS_VTA. LFS does its default grid reordering at the same time as it sends the IS_VTA (VoTe Action) and you can override this by sending an IS_REO.

To request an IS_REO packet at any time, send this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_REO (request an IS_REO)

TRACKING PACKET REQUESTS

To request players, connections, results or a single NLP or MCI, send an IS_TINY

In each case, ReqI must be non-zero, and will be returned in the reply packet

AUTOCROSS

When all objects are cleared from a layout, LFS sends this IS_TINY :

ReqI : 0
SubT : TINY_AXC (AutoX Cleared)

You can request information about the current layout with this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_AXI (AutoX Info)

The information will be sent back in this packet (also sent when a layout is loaded)

On false start or wrong route / restricted area, an IS_PEN packet is sent :

If an autocross object is hit (2 second time penalty) this packet is sent.

CAR TRACKING

car position info sent at constant intervals

To receive IS_NLP or IS_MCI packets at a specified interval :

  1. ) Set the Interval field in the IS_ISI (InSimInit) packet (50, 60, 70... 8000 ms)
  2. ) Set one of the flags ISF_NLP or ISF_MCI in the IS_ISI packet

If ISF_NLP flag is set, one IS_NLP packet is sent...

If ISF_MCI flag is set, a set of IS_MCI packets is sent...

You can change the rate of NLP or MCI after initialisation by sending this IS_SMALL :

ReqI : 0
SubT : SMALL_NLI (Node Lap Interval)
UVal : interval (0 means stop, otherwise time interval : 50, 60, 70... 8000 ms)

CAR POSITION PACKETS

(Initialising OutSim from InSim - See OutSim)

To request Car Positions from the currently viewed car, send this IS_SMALL :

ReqI : 0
SubT : SMALL_SSP (Start Sending Positions)
UVal : interval (time between updates - zero means stop sending)

If OutSim has not been setup in cfg.txt, the SSP packet makes LFS send UDP packets if in game, using the OutSim system as documented near the end of this text file.

You do not need to set any OutSim values in LFS cfg.txt - OutSim is fully initialised by the SSP packet.

The OutSim packets will be sent to the UDP port specified in the InSimInit packet.

NOTE :
OutSim packets are not InSim packets and don't have a 4-byte header.

DASHBOARD PACKETS

(Initialising OutGauge from InSim - See OutGauge)

To request Dashboard Packets from the currently viewed car, send this IS_SMALL :

ReqI : 0
SubT : SMALL_SSG (Start Sending Gauges)
UVal : interval (time between updates - zero means stop sending)

If OutGauge has not been setup in cfg.txt, the SSG packet makes LFS send UDP packets if in game, using the OutGauge system as documented near the end of this text file.

You do not need to set any OutGauge values in LFS cfg.txt - OutGauge is fully initialised by the SSG packet.

The OutGauge packets will be sent to the UDP port specified in the InSimInit packet.

NOTE :
OutGauge packets are not InSim packets and don't have a 4-byte header.

CAMERA CONTROL

IN GAME camera control

You can set the viewed car and selected camera directly with a special packet These are the states normally set in game by using the TAB and V keys

DIRECT camera control

A Camera Position Packet can be used for LFS to report a camera position and state. An InSim program can also send one to set LFS camera position in game or SHIFT+U mode.

SMOOTH CAMERA POSITIONING

The "Time" value in the packet is used for camera smoothing. A zero Time means instant positioning. Any other value (milliseconds) will cause the camera to move smoothly to the requested position in that time. This is most useful in SHIFT+U camera modes or for smooth changes of internal view when using the ISS_VIEW_OVERRIDE flag.

NOTE :
You can use frequently updated camera positions with a longer Time value than the update frequency. For example, sending a camera position every 100 ms, with a Time value of 1000 ms. LFS will make a smooth motion from the rough inputs.
If the requested camera mode is different from the one LFS is already in, it cannot move smoothly to the new position, so in this case the "Time" value is ignored.

GETTING A CAMERA PACKET

To GET a CamPosPack from LFS, send this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_SCP (Send Cam Pos)

LFS will reply with a IS_CPP CamPosPack as described above. You can store this packet and later send back exactly the same packet to LFS and it will try to replicate that camera position.

TIME CONTROL

Request the current time at any point with this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_GTH (Get Time in Hundredths)

The time will be sent back in this IS_SMALL :

ReqI : non-zero (as received in the request packet)
SubT : SMALL_RTP (Race Time Packet)
UVal : Time (hundredths of a second since start of race or replay)

You can stop or start time in LFS and while it is stopped you can send packets to move time in steps. Time steps are specified in hundredths of a second. Warning : unlike pausing, this is a "trick" to LFS and the program is unaware of time passing so you must not leave it stopped because LFS is unusable in that state. This packet is not available in live multiplayer mode.

Stop and Start with this IS_SMALL :

ReqI : 0
SubT : SMALL_TMS (TiMe Stop)
UVal : stop (1 - stop / 0 - carry on)

When STOPPED, make time step updates with this IS_SMALL :

ReqI : 0
SubT : SMALL_STP (STeP)
UVal : number (number of hundredths of a second to update)

REPLAY CONTROL

You can load a replay or set the position in a replay with an IS_RIP packet. Replay positions and lengths are specified in hundredths of a second. LFS will reply with another IS_RIP packet when the request is completed.

You can request an IS_RIP packet at any time with this IS_TINY :

ReqI : non-zero (returned in the reply)
SubT : TINY_RIP (Replay Information Packet)

SCREENSHOTS

You can instuct LFS to save a screenshot using the IS_SSH packet. The screenshot will be saved as an uncompressed BMP in the data\shots folder. BMP can be a filename (excluding .bmp) or zero - LFS will create a file name. LFS will reply with another IS_SSH when the request is completed.

BUTTONS

You can make up to 240 buttons appear on the host or guests (ID = 0 to 239). You should set the ISF_LOCAL flag (in IS_ISI) if your program is not a host control system, to make sure your buttons do not conflict with any buttons sent by the host.

LFS can display normal buttons in these four screens :

The recommended area for most buttons is defined by.

If you draw buttons in this area, the area will be kept clear to avoid overlapping LFS buttons with your InSim program's buttons. Buttons outside that area will not have a space kept clear. You can also make buttons visible in all screens - see below.

To delete one button or clear all buttons, send this packet.

NOTE :
BFN_REQUEST allows the user to bring up buttons with SHIFT+B or SHIFT+I

To send a button to LFS, send this variable sized packet.

Host buttons and local buttons are stored separately, so there is no chance of a conflict between a host control system and a local system (although the buttons could overlap on screen).

Programmers of local InSim programs may wish to consider using a configurable button range and possibly screen position, in case their users will use more than one local InSim program at once.

On clicking the button, a text entry dialog will be opened, allowing the specified number of characters to be typed in. The caption on the text entry dialog is optionally customisable using Text in the IS_BTN packet. If the first character of IS_BTN's Text field is zero, LFS will read the caption up to the second zero. The visible button text then follows that second zero.

Replies : If the user clicks on a clickable button, this packet will be sent.

If the TypeIn byte is set in IS_BTN the user can type text into the button In that case no IS_BTC is sent - an IS_BTT is sent when the user presses ENTER

OutSim - MOTION SIMULATOR SUPPORT

The user's car in multiplayer or the viewed car in single player or single player replay can output information to a motion system while viewed from an internal view.

This can be controlled by 5 lines in the cfg.txt file :

 OutSim Mode 0        :0-off 1-driving 2-driving+replay
 OutSim Delay 1       :minimum delay between packets (100ths of a sec)
 OutSim IP 0.0.0.0    :IP address to send the UDP packet
 OutSim Port 0        :IP port
 OutSim ID 0          :if not zero, adds an identifier to the packet

Each update sends the following UDP packet.

OutGauge - EXTERNAL DASHBOARD SUPPORT

The user's car in multiplayer or the viewed car in single player or single player replay can output information to a dashboard system while viewed from an internal view.

This can be controlled by 5 lines in the cfg.txt file :

 OutGauge Mode 0        :0-off 1-driving 2-driving+replay
 OutGauge Delay 1       :minimum delay between packets (100ths of a sec)
 OutGauge IP 0.0.0.0    :IP address to send the UDP packet
 OutGauge Port 0        :IP port
 OutGauge ID 0          :if not zero, adds an identifier to the packet

Each update sends the following UDP packet.

Generated on Wed Apr 28 11:50:47 2010 for InSim by  doxygen 1.5.8