Crate insim

insim

insim is a Rust library for working with the Racing Simulator Live For Speed.

It’s primary use case is to communicate with LFS via Insim, however it also provides additional utilities for working with LFS as a whole through feature flags and it’s sibling crates.

The intention is to provide a strongly typed, native rust implementation, rather than a thin layer over a series of bytes.

Many of the core types, such as Vehicle, Track, etc. have been housed within the crate insim_core, which is re-exported.

You will probably want to use https://en.lfsmanual.net/wiki/InSim.txt as a detailed reference for what each packet describes and can do. Where possible this crate aligns the naming of fields in packets to match the original spec. In a handful of circumstances we have needed to rename, or separate some fields (most notably thrbrk and cluhan in the Con packet).

Supported Features

• insim over TCP or UDP
• insim over TCP and Websocket via LFS World Relay

Feature flags

The following are a list of [Cargo features][cargo-features] that can be enabled or disabled:

Name	Description	Default?
serde	Enable serde support	No
pth	Pull in insim_pth and re-export	No
smx	Pull in insim_smx and re-export	No
tokio	Enable tokio support	Yes
blocking	Enable blocking/sync support	Yes
websocket	Enable LFSW Relay support over websocket using Tungstenite (requires tokio)	Yes

Making a TCP connection (using tokio)

let conn = insim::tcp("127.0.0.1:29999").connect_async().await?;
loop {
    let packet = conn.read().await?;
    println!("{:?}", packet);

    match packet {
        insim::Packet::Mci(_) => {
          println!("Got a MCI packet!")
        },
        _ => {},
    }
}

Making a TCP connection (using blocking)

let conn = insim::tcp("127.0.0.1:29999").connect()?;
loop {
    let packet = conn.read()?;
    println!("{:?}", packet);

    match packet {
        insim::Packet::Mci(_) => {
          println!("Got a MCI packet!")
        },
        _ => {},
    }
}

Making a LFS World Relay connection (using tokio)

let conn = insim::relay()
    .relay_select_host("Nubbins AU Demo")
    .connect_async()
    .await?;

loop {
    let packet = conn.read().await?;
    println!("{:?}", packet);

    match packet {
        insim::Packet::Mci(_) => {
          println!("Got a MCI packet!")
        },
        _ => {},
    }
}

Making a UDP connection (using tokio)

let conn = insim::tcp("127.0.0.1:29999", None).connect_async().await?;
loop {
    let packet = conn.read().await?;
    println!("{:?}", packet);

    match packet {
        insim::Packet::Mci(_) => {
          println!("Got a MCI packet!")
        },
        _ => {},
    }
}

Additional examples

For further examples see https://github.com/theangryangel/insim.rs/tree/main/examples

Re-exports

• pub use insim_core as core;

Modules

• identifiers
  Various identifiers used within insim, such as RequestId, ConnectionId, etc.
• insim
  Definitions for the Insim packets and related bitflags, enums, etc.
• net
  Network implementation
• relay
  Definitions for the Insim Relay packets. 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.

Structs

• Builder

Enums

• Error
  The Errors that may occur during an Insim connection.
• Packet
  Enum representing all possible packets receivable via an Insim connection. Each variant may either be instructional (tell LFS to do something), informational (you are told something about LFS), or both.

Constants

• LFSW_RELAY_ADDR
  The LFS World Relay address and port
• VERSION
  The Insim Protocol Version Number supported by this library

Functions

• relay
  Shortcut method to create a LFS World Relay connection.
• tcp
  Shortcut method to create a TCP connection
• udp
  Shortcut method to create a UDP connection. If local_addr is not provided then we will bind to “0.0.0.0:0” (all addresses, random port).

Type Aliases

• Result
  A Result alias where the Err case is insim::Error.