Node InSim

An InSim library for Node.js with TypeScript support.

Introduction

Node InSim provides a JavaScript API to communicate with the Live for Speed InSim protocol over a TCP connection. After connecting to an LFS host via a hostname and a port, you are able to send InSim packets to the host and receive incoming packets from the host.

All packet structures in Node InSim are identical to the structs defined in the InSim protocol. All packet classes with all their properties are documented according to the specification.

InSim compatibility

Node InSim is compatible with InSim version 10.

Installation

Install the node-insim NPM package in your Node.js application:

npm install --save node-insim

or if you use Yarn:

yarn add node-insim

Documentation

For more detailed documentation of the public API, see https://simbroadcasts.github.io/node-insim/.

Usage

Connecting

To connect to an LFS host, you must enter its hostname, a port and a short name of your InSim application.

The InSim port must be configured in the LFS host settings. Also, make sure the public IP address from which your application is connecting is allowed to connect to the host's InSim port.

Single host

import{InSim}from'node-insim';constinSim=newInSim();inSim.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});

Multiple hosts

To connect to multiple hosts at once, create a new InSim instance for each host.

import{InSim}from'node-insim';constinSim1=newInSim();inSim1.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});constinSim2=newInSim();inSim2.connect({Host: '127.0.0.2',Port: 30000,IName: 'Node InSim App',});

TCP / UDP

By default, Node InSim opens a TCP connection. If you want to use UDP, set the Protocol option to UDP in the connect function.

import{InSim}from'node-insim';constinSim=newInSim();inSim.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',Protocol: 'UDP',});

Sending packets

InSim packets can be sent using the send() method on the InSim class instance, which takes a single argument - the packet class instance.

A fast way to set packet properties is to populate them in the class constructor:

import{InSim}from'node-insim';import{IS_TINY,TinyType}from'node-insim/packets';constinSim=newInSim();inSim.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});inSim.send(newIS_TINY({ReqI: 1,SubT: TinyType.TINY_PING,}),);

Another way is to assign each property after creating the instance:

import{InSim}from'node-insim';import{IS_TINY,TinyType}from'node-insim/packets';constinSim=newInSim();inSim.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});constpingPacket=newIS_TINY();pingPacket.ReqI=1;pingPacket.SubT=TinyType.TINY_PING;inSim.send(pingPacket);

Waiting for packets

There are cases when you want to send a packet and then wait for a response in another packet. There is a helper method sendAwait() which waits for a given packet type and when it's received, it's resolved as a Promise. It also makes sure that the received packet's ReqI property matches the one entered in the sent packet.

import{InSim}from'node-insim';import{IS_TINY,PacketType,TinyType}from'node-insim/packets';constinSim=newInSim();inSim.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});inSim.sendAwait(newIS_TINY({ReqI: 1,SubT: TinyType.TINY_SST,}),PacketType.ISP_STA,).then((packet)=>{console.log(packet.NumConns);});

You can filter the received packet by its data using a callback in the 3rd argument:

import{InSim}from'node-insim';import{IS_TINY,PacketType,TinyType}from'node-insim/packets';constinSim=newInSim();inSim.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});inSim.sendAwait(newIS_TINY({ReqI: 1,SubT: TinyType.TINY_GTP,}),PacketType.ISP_SMALL,({ SubT })=>SubT===SmallType.SMALL_RTP,).then((packet)=>{console.log('session time',packet.UVal);});

Request-reply packet pairs

Name	Request packet	Reply packet
Ping	IS_TINY SubT: TinyType.TINY_PING	IS_TINY SubT: TinyType.TINY_REPLY
Session time	IS_TINY SubT: TinyType.TINY_GTP	IS_SMALL SubT: SmallType.SMALL_RTP
State	IS_TINY SubT: TinyType.TINY_SST	IS_STA
InSim multi	TINY_ISM	IS_ISM

Sending messages

The InSim class has helper methods useful for sending messages to LFS.

Send a message which will appear on the local computer only

inSim.sendLocalMessage('Local message');

Send a command

inSim.sendMessage('/end');

Send a message

• up to 63 characters - send an IS_MST packet
• 64 characters or more - send an IS_MSX packet

inSim.sendMessage('This is a message');

Send a message to a specific connection by their UCID

inSim.sendMessageToConnection(4,'This is a message targeting UCID 4');

Send a message to a specific player by their PLID

inSim.sendMessageToPlayer(4,'This is a message targeting PLID 4');

Receiving packets

The InSim class exposes an on() method, which is used to listen for incoming packets by their type.

import{InSim}from'node-insim';import{InSimPacketInstance,PacketType}from'node-insim/packets';constinSim=newInSim();inSim.on(PacketType.ISP_VER,onVersion);functiononVersion(packet: InSimPacketInstance<PacketType.ISP_VER>){console.log(`Connected to LFS ${packet.Product}${packet.Version}`);}

The event callback contains the received packet, and an optional second argument - the InSim instance which received that packet. You can use that instance to send additional packets in response.

import{InSim}from'node-insim';import{InSimPacketInstance,PacketType,TinyType}from'node-insim/packets';importtype{IS_TINY}from'node-insim/packets';constinSim=newInSim();inSim.on(PacketType.ISP_VER,onVersion);functiononVersion(packet: InSimPacketInstance<PacketType.ISP_VER>,inSim: InSim,){inSim.send(newIS_TINY({ReqI: 1,SubT: TinyType.TINY_PING,}),);}

Multiple hosts

You can use the inSim argument in the event handler callback to identify the source host of the received packets, for instance by the options.Host property.

Alternatively, the InSim class constructor accepts an optional id argument, which can also be used to tell apart the InSim connections.

import{InSim}from'node-insim';import{InSimPacketInstance,PacketType}from'node-insim/packets';constinSim1=newInSim('Host One');inSim1.connect({Host: '127.0.0.1',Port: 29999,IName: 'Node InSim App',});constinSim2=newInSim('Host Two');inSim2.connect({Host: '127.0.0.2',Port: 30000,IName: 'Node InSim App',});inSim1.on(PacketType.ISP_VER,onVersion);inSim2.on(PacketType.ISP_VER,onVersion);functiononVersion(packet: InSimPacketInstance<PacketType.ISP_VER>,inSim: InSim,){console.log(`Connected to ${inSim.options.Host}:${inSim.options.Port}`);if(inSim.id){console.log(`InSim connection ID: ${inSim.id}`);}}

String encoding

All strings in received or sent packets are automatically converted from LFS encoding to Unicode and vice versa.

If you need to access the raw LFS-encoded string in a received packet, use the _raw property in the packet instance, which contains all unconverted string properties.

import{InSim}from'node-insim';import{PacketType}from'node-insim/packets';constinSim=newInSim();inSim.on(PacketType.ISP_ISM,(packet)=>{console.log(packet.HName);// UTF-8 string - ^1Drifter Team ^7★ Serverconsole.log(packet._raw.HName);// raw string - ^1Drifter Team ^7^J�� Server\u0000\u0000\u0000\u0000});

When you send a Unicode string value in a packet, each character will get encoded into the correct LFS encoding, so LFS can display the text in a message or a button.

import{InSim}from'node-insim';import{PacketType}from'node-insim/packets';importtype{IS_MSL}from'node-insim/packets';constinSim=newInSim();inSim.on(PacketType.ISP_VER,(packet)=>{inSim.send(newIS_MSL({Msg: 'čau světe',// LFS will receive: ^Eèau svìte}),);});

Special characters

Special care needs to be taken when sending strings containing caret (^) and slash (/) characters:

• A caret needs to be escaped as ^^ because the caret symbol acts as an escape character in LFS. Sending ^^hello as a message will display ^hello in LFS. Sending just ^hello would appear as #ello.
• A slash needs to be escaped as ^s, otherwise it is treated as an LFS in-game command prefix when used in a message packet. Sending ^sjoin as a message will display /join in LFS, whereas sending /join will make the player join the track.

OutGauge

import{OutGauge}from'node-insim';constoutGauge=newOutGauge();outGauge.connect({Host: '127.0.0.1',Port: 29999,});outGauge.on('packet',(data)=>{console.clear();console.log(data.RPM);});

OutSim

import{OutSim,OutSimPack}from'node-insim';constoutSim=newOutSim();outSim.connect({Host: '127.0.0.1',Port: 29999,});outSim.on('packet',(data)=>{// Make sure the simple OutSimPack packet is really received, as opposed to OutSimPack2if(!(datainstanceofOutSimPack)){return;}console.clear();console.log(data.PosX);});

Debugging

Node InSim uses the debug NPM package for debug logs. By default, Node InSim does not output any logs to the standard output.

To enable logging, use the DEBUG environment variable when running your InSim application. All logs are prefixed with node-insim. You can use wildcards to filter out the logs that you need.

DEBUG=* node insim.js # debug all messages
DEBUG=node-insim:tcp node insim.js # debug only TCP protocol messages

Example applications

You can find example applications using Node InSim in the examples folder.

Example
InSim connection	JavaScript + CJS	TypeScript + ESM
InSim connection (multiple hosts)	JavaScript + CJS	TypeScript + ESM
InSim connection (UDP)	JavaScript + CJS	TypeScript + ESM
OutGauge	JavaScript + CJS	TypeScript + ESM
OutGauge with InSim buttons	JavaScript + CJS	TypeScript + ESM
OutSim	JavaScript + CJS	TypeScript + ESM
OutSim with Options	JavaScript + CJS	TypeScript + ESM

Before you run an example, follow the instructions in each example's README.md file.

For instance, to run the "InSim connection - TypeScript" example, run the following commands:

cd examples/typescript/insim-connection
npm install
npm start

Development

Requirements

• Node.js 18
• Yarn

Start a development server

yarn dev

Code generators

When adding new InSim packets to the library, you can use built-in code generators using yarn generate. It will create and update all the necessary files for you.

Run unit tests

yarn test

Run tests against a real LFS application

To run these tests, LFS must be running with an InSim port open.

By default, the tests connect to 127.0.0.1:29999. The InSim host and port can be configured by copying .env to .env.local in the lfs-test directory.

yarn test:lfs

Build all example applications

This command will go through each application in the examples/ folder, install its dependencies, then build the application (typescript only).

yarn test:examples

Lint code

yarn lint

Format code

yarn format

Production build

Compiled files will be created in dist/.

yarn build

Run all checks at once

You can run code format, lint + fix, build and test with the following command:

yarn check-all

Releases

This project uses Changesets to manage publishing and release notes.

Making changes

Before committing a bug fix, a new feature or a breaking change, run the following command to create a changeset:

yarn changeset

1. When prompted, choose if it's a patch, minor or a major change.
2. Enter a summary for the change which will appear in the changelogs.
3. When confirmed, a changeset Markdown file will be created in the .changeset directory.
4. Commit the new changeset file along with your source code changes.

Releasing a new version

To bump the package version:

1. Go to the GitHub Actions page of this repo.
2. Select the Release workflow.
3. Click "Run workflow".

This will bump Node InSim version according to the types of changes in the changesets and create a pull request. You can review the changes and merge the pull request once it's ready.

Once the version has been bumped, trigger the Release workflow again, which will publish a new version to NPM.

---