API¶

This page describes the public API of xi4n at it’s core. It’s a work in progress since xi4n is a platform first and a library second, its API is mainly undocumented, but is reasonably stable.

If you’re planning on using xi4n as a library, honestly I highly recommend reading the source of xi4n code. xi4n itself is using the same modules that you can require(), thus it’s always going to be the most up to date repository of information.

Basic usage¶

Specify xi4n as a dependency in your package.json.
Run npm install as you would normally to pull down the new dependency.
In your code var xi4n = require(‘xi4n’);.
Hack. Hack. Hack.

xi4n.protocols.manager¶

Manages a collection of clients; insim, outsim, outgauge or relay.

class xi4n.protocols.manager(options)¶

Manages one or more clients. Clients are automatically created and setup from options object.

Arguments:	options (object) – An object of options

xi4n.protocols.manager.start()¶: Attempts to start/connect all associated clients.

xi4n.protocols.manager.stop()¶: Attempts to stop/disconnect all associated clients.

xi4n.protocols.insim¶

class xi4n.protocols.insim(options[, log])¶

An insim client. Implements the insim protocol, and also understands and decodes outsim and outgauge, when setup to be sent over insim.

Emit events, named the same as the insim, outsim, or outgauge packet name.

Arguments:	options (object) – An object of options log (object) – Optional logger. An instance of winston, or compatible logger is required. If none provided all log entries go into a black hole.

xi4n.protocols.insim.connect()¶: Attempts to establish a connection.

xi4n.protocols.insim.disconnect()¶: Disconnects any active connections.

xi4n.protocols.insim.send(data)¶

Sends data down any active insim connection.

Arguments:	data (object) – An instance of an object. Must implement pack() function that returns a binary string of an insim packet.

xi4n.protocols.insim.on(event, callback)¶

Arguments:	event (string) – Event you’re listening for. Typically an insim packet

name. :param function callback: Function that is called when the event is received.

Adds a callback to run, when event is emitted.

xi4n.protocols.insim.off(event, callback)¶

Removes a callback from the event queue.

Arguments:	event (string) – Event you want to remove the callback from. callback (function) – Callback you want to remove.

xi4n.protocols.outsim¶

class xi4n.protocols.outsim(options[, log])¶

An outsim client. Implements the outsim protocol.

Emit events, named the same as the outsim packet.

Arguments:	options (object) – An object of options log (object) – Optional logger. An instance of winston, or compatible logger is required. If none provided all log entries go into a black hole.

xi4n.protocols.outsim.connect()¶: Creates a listening UDP socket.

xi4n.protocols.outsim.disconnect()¶: Kills the listening socket.

xi4n.protocols.outsim.on(event, callback)¶

Adds a callback to run, when event is emitted.

Arguments:	event (string) – Event you’re listening for. Typically an outsim packet name. callback (function) – Function that is called when the event is received.

xi4n.protocols.outsim.off(event, callback)¶

Removes a callback from the event queue.

Arguments:	event (string) – Event you want to remove the callback from. callback (function) – Callback you want to remove.

xi4n.protocols.outgauge¶

class xi4n.protocols.outsim(options[, log])

An outsim client. Implements the outgauge protocol.

Emit events, named the same as the outgauge packet.

Arguments:	options (object) – An object of options log (object) – Optional logger. An instance of winston, or compatible logger is required. If none provided all log entries go into a black hole.

xi4n.protocols.outsim.connect(): Creates a listening UDP socket.

xi4n.protocols.outsim.disconnect(): Kills the listening socket.

xi4n.protocols.outgauge.on(event, callback)¶

Adds a callback to run, when event is emitted.

Arguments:	event (string) – Event you’re listening for. Typically an outgauge packet name. callback (function) – Function that is called when the event is received.

xi4n.protocols.outgauge.off(event, callback)¶

Removes a callback from the event queue.

Arguments:	event (string) – Event you want to remove the callback from. callback (function) – Callback you want to remove.

xi4n.protocols.relay¶

class xi4n.protocols.relay(options[, log])¶

LFS World relay client. Implements the both relay and insim protocols.

Emit events, named the same as the insim or relay packet.

Arguments:	options (object) – An object of options log (object) – Optional logger. An instance of winston, or compatible logger is required. If none provided all log entries go into a black hole.

xi4n.protocols.relay.connect()¶: Creates a connection to the LFS World relay.

xi4n.protocols.relay.select(host[, admin_password[, spectator_password]])¶

Convenience function that sends a IR_SEL packet to the LFS World relay and selects a host to receive data from.

Arguments:	host (string) – Host you want to select to receive insim data from. admin_password (string) – Optional administrator password for host. spectator_password (string) – Optional spectator password for host.

xi4n.protocols.relay.disconnect()¶: Disconnects from the LFS World relay.

xi4n.protocols.relay.send(data)¶

Arguments:	data (object) – An instance of an object. Must implement pack() function that returns a binary string of a relay packet.

xi4n.protocols.relay.on(event, callback)¶

Adds a callback to run, when event is emitted.

Arguments:	event (string) – Event you’re listening for. Typically an insim or relay packet name. callback (function) – Function that is called when the event is received.

xi4n.protocols.relay.off(event, callback)¶

Removes a callback from the event queue.

Arguments:	event (string) – Event you want to remove the callback from. callback (function) – Callback you want to remove.

xi4n.product¶

xi4n.product.basedir¶: The base directory of the xi4n install.

xi4n.product.name¶: The name of the product (read from package.json)

xi4n.product.bversion¶: The version of the product (read from package.json). Semver compatible.

xi4n.product.bfull¶: Full product string - product name and version number.

xi4n.strings¶

Provides a bunch of useful functions to deal with LFS’ codepages and special codes - such as colours.

xi4n.strings.toUTF8(string)¶

Converts a LFS string to a UTF-8 string. Colour codes are not removed.

Arguments:	string (string) – Input string from LFS.

xi4n.strings.translateSpecials(string)¶

Convers special characters into their UTF-8 equivilent, such as ^^ into ^.

Arguments:	string (string) – Input string from LFS.

xi4n.strings.remColours(string)¶

Removes colour codes from a LFS string, replacing them with nothing.

Arguments:	string (string) – Input string from LFS.

xi4n.data.pth¶

xi4n.data.pth.get(track)¶

Returns a pth file, converted into json for convenience.

Arguments:	track (string) – Short track name i.e. BL1.

xi4n.data.vehicle¶

xi4n.data.vehicle.all¶

Contains an array of vehicles, and their relevant facts.

Example return format:

[
        { short: 'XFG', long: 'XF GTI', layout: 'Hatchback', drive: 'FWD', kw: 86, bhp: 115, kg: 942, lb: 2076, demo: true, s1: true, s2: true },
    ...
    { short: 'FZR', long: 'FZ50 GTR', layout: 'Race', drive: 'RWD', kw: 465, bhp: 490, kg: 110, lb: 2425, demo: false, s1: false, s2: true }
]

xi4n.data.vehicle.findBy(callback)¶

Returns an array of vehicles, and their relevant facts, filtered by callback.

Arguments:	callback (function) – Callback used to filter vehicles.

xi4n.data.vehicle.countBy(callback)¶

Counts the number of vehicles that match the filtering callback.

Arguments:	callback (function) – Callback used to filter vehicles.

xi4n.data.vehicle.randomOneBy([callback])¶

Returns a single vehicle, optionally filtered by a callback.

Arguments:	callback (function) – Optional Callback used to filter vehicles.

xi4n.data.track¶

xi4n.data.track.all¶

Contains an array of track, and their relevant facts.

Example return format:

[
    { short: 'BL1', long: 'Blackwood GP', km: 3.307, mi: 2.055, grid: 32, s1: true, s2: true, demo: true, reversible: true },
    ...
    { short: 'AS7', long: 'Aston North', km: 5.168, mi: 3.211, grid: 32, s1: false, s2: true, demo: false, reversible: true }
]

xi4n.data.track.findBy(callback)¶

Returns an array of tracks, and their relevant facts, filtered by callback.

Arguments:	callback (function) – Callback used to filter tracks.

xi4n.data.track.countBy(callback)¶

Counts the number of vehicles that match the filtering callback.

Arguments:	callback (function) – Callback used to filter vehicles.

xi4n.data.track.randomOneBy([callback])¶

Returns a single track, optionally filtered by a callback.

Arguments:	callback (function) – Optional Callback used to filter tracks.