Crate insim

Expand description

A friendly, Rust idiomatic library for the InSim protocol used by Live for Speed racing simulator.

The focus of this library is providing a high level, strongly typed, primitives that are difficult to misuse and have reasonable performance, rather than be a thin layer over a series of bytes.

Where possible this crate aligns the naming of fields in packets to match the original Insim specification.

In a handful of circumstances we have needed to rename, or separate some fields to align with the crate’s key focus.

§High-level features

Here is a non-exhaustive list of the things that insim supports:

insim over TCP or UDP (for both blocking and tokio). Mixing and matching TCP and UDP for positional updates is possible, but requires you to drop to the “sans-io” approach.
insim via LFS World Relay over TCP and Websocket (for both blocking and tokio).
Or sans-io/bring-your-own-IO of your own choice through the crate::net::Codec.

§Usage

insim is on crates.io and can be used by adding insim to your dependencies in your project’s Cargo.toml. Or more simply, just run cargo add insim.

If you want to use an unreleased version you can also reference the GitHub repository.

You might also find these related crates useful:

insim_pth – for reading and writing LFS PTH files
insim_smx – for reading and writing LFS SMX files
outgauge - “sans-io” implementation of the LFS outgauge protocol
outsim - “sans-io” implementation of the LFS outsim protocol

They follow the same design focus and can be found in the same GitHub repository.

§Examples

Looking for more examples? Take a look at our more detailed examples here: https://github.com/theangryangel/insim.rs/tree/main/examples – it’s full of practical code to help you get started.

§Async TCP Connection

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!")
        },
        _ => {},
    }
}

§Blocking TCP Connection

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!")
        },
        _ => {},
    }
}

§Async LFSW Relay Connection

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!")
        },
        _ => {},
    }
}

§Async UDP Connection

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!")
        },
        _ => {},
    }
}

§Crate features

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

Name	Description	Default?
`serde`	Enable serde support	No
`tokio`	Enable tokio support	Yes
`blocking`	Enable blocking/sync support	Yes

Re-exports§

pub use packet::Packet;
pub use packet::WithRequestId;
pub use insim_core as core;

Modules§

addressblocking or tokio: Handle ToSocketAddrs ownership issues
builderblocking or tokio: Tools to build a connection to LFS using Insim
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
packet: Contains crate::Packet enum
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.

Enums§

Error: The Errors that may occur during an Insim connection.

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.
tcpblocking or tokio: Shortcut method to create a TCP connection
udpblocking or tokio: 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.

Crate insimCopy item path