|
InSim
0.6c
Documentation of Live for Speed InSim Protocol
|
|
InSim
0.6c
Documentation of Live for Speed InSim Protocol
|
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.
Version 0.6B (INSIM_VERSION increased to 5)
Version 0.6C
all multi-byte types are PC style - lowest byte first
All InSim packets use a four byte header
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.
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.
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.
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).
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)
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)
These states can be set by a special packet :
Other states must be set by using keypresses or messages (see below)
You can send this packet to LFS to set the screen mode.
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.
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.
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)
LFS notifies the external program of any votes to restart or qualify
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)
You can send a IS_PLC packet to limit the cars that can be used by a given connection The resulting set of selectable cars is a subset of the cars set to be available on the host (by the /cars command)
For example :
Cars = 0 ... no cars can be selected on the specified connection
Cars = 0xffffffff ... all the host's available cars can be selected
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 :
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 race 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 SMALL_VTA (VoTe Action). LFS does its default grid reordering at the same time as it sends the SMALL_VTA and you can override this by sending an IS_REO.
You can send one to LFS in two different ways, to specify the starting order :
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)
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
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.
To receive IS_NLP or IS_MCI packets at a specified interval :
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 : 40, 50, 60... 8000 ms)
reports contacts between two cars if the closing speed is above 0.25 m/s
Set the ISF_CON flag in the IS_ISI to receive car contact reports
Set the ISF_OBH flag in the IS_ISI to receive object contact reports
Set the ISF_HLV flag in the IS_ISI to receive reports of incidents that would violate HLVC
reporting / adding / removing
Set the ISF_AXM_LOAD flag in the IS_ISI for info about objects when a layout is loaded.
Set the ISF_AXM_EDIT flag in the IS_ISI for info about objects edited by user or InSim.
You can also add or remove objects by sending IS_AXM packets. Some care must be taken with these - please read the notes.
(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.
(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.
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
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.
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.
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.
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.
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)
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)
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.
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.
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
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.
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.
1.7.6.1
