node insim

Nodo InSim

Una biblioteca InSim para Node.js con soporte TypeScript.

Introducción

Node InSim proporciona una API de JavaScript para comunicarse con el protocolo Live for Speed ​​InSim a través de una conexión TCP. Después de conectarse a un host LFS a través de un nombre de host y un puerto, podrá enviar paquetes InSim al host y recibir paquetes entrantes del host.

Todas las estructuras de paquetes en Node InSim son idénticas a las estructuras definidas en el protocolo InSim. Todas las clases de paquetes con todas sus propiedades están documentadas según la especificación.

Compatibilidad InSim

Node InSim es compatible con la versión 9 de InSim.

Instalación

Instale el paquete NPM node-insim en su aplicación Node.js:

npm install --save node-insim

o si usas Yarn:

yarn add node-insim

Documentación

Para obtener documentación más detallada de la API pública, consulte https://simroadcasts.github.io/node-insim/.

Uso

Conectando

Para conectarse a un host LFS, debe ingresar su nombre de host, un puerto y un nombre corto de su aplicación InSim.

El puerto InSim debe configurarse en la configuración del host LFS. Además, asegúrese de que la dirección IP pública desde la que se conecta su aplicación pueda conectarse al puerto InSim del host.

anfitrión único

 import { InSim } from 'node-insim' ;

const inSim = new InSim ( ) ;

inSim . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
  IName : 'Node InSim App' ,
} ) ; 

Múltiples hosts

Para conectarse a varios hosts a la vez, cree una nueva instancia InSim para cada host.

 import { InSim } from 'node-insim' ;

const inSim1 = new InSim ( ) ;

inSim1 . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
  IName : 'Node InSim App' ,
} ) ;

const inSim2 = new InSim ( ) ;

inSim2 . connect ( {
  Host : '127.0.0.2' ,
  Port : 30000 ,
  IName : 'Node InSim App' ,
} ) ; 

TCP/UDP

De forma predeterminada, Node InSim abre una conexión TCP. Si desea utilizar UDP, configure la opción Protocol en UDP en la función connect .

 import { InSim } from 'node-insim' ;

const inSim = new InSim ( ) ;

inSim . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
  IName : 'Node InSim App' ,
  Protocol : 'UDP' ,
} ) ;

enviando paquetes

Los paquetes InSim se pueden enviar utilizando el método send() en la instancia de la clase InSim , que toma un único argumento: la instancia de la clase del paquete.

Una forma rápida de configurar las propiedades de los paquetes es completarlas en el constructor de clases:

 import { InSim } from 'node-insim' ;
import { IS_TINY , TinyType } from 'node-insim/packets' ;

const inSim = new InSim ( ) ;

inSim . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
  IName : 'Node InSim App' ,
} ) ;

inSim . send (
  new IS_TINY ( {
    ReqI : 1 ,
    SubT : TinyType . TINY_PING ,
  } ) ,
) ;

Otra forma es asignar cada propiedad después de crear la instancia:

 import { InSim } from 'node-insim' ;
import { IS_TINY , TinyType } from 'node-insim/packets' ;

const inSim = new InSim ( ) ;

inSim . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
  IName : 'Node InSim App' ,
} ) ;

const pingPacket = new IS_TINY ( ) ;
pingPacket . ReqI = 1 ;
pingPacket . SubT = TinyType . TINY_PING ;

inSim . send ( pingPacket ) ;

enviando mensajes

La clase InSim tiene métodos auxiliares útiles para enviar mensajes a LFS.

Envíe un mensaje que aparecerá solo en la computadora local

 inSim . sendLocalMessage ( 'Local message' ) ; 

enviar un comando

 inSim . sendMessage ( '/end' ) ; 

enviar un mensaje

• hasta 63 caracteres: envíe un paquete IS_MST
• 64 caracteres o más: envíe un paquete IS_MSX

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

Enviar un mensaje a una conexión específica por su UCID

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

Enviar un mensaje a un jugador específico por su PLID

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

Recibir paquetes

La clase InSim expone un método on() , que se utiliza para escuchar paquetes entrantes por su tipo.

 import { InSim } from 'node-insim' ;
import type { IS_VER } from 'node-insim/packets' ;
import { PacketType } from 'node-insim/packets' ;

const inSim = new InSim ( ) ;

inSim . on ( PacketType . ISP_VER , onVersion ) ;

function onVersion ( packet : IS_VER ) {
  console . log ( `Connected to LFS ${ packet . product } ${ packet . Version } ` ) ;
}

La devolución de llamada del evento contiene el paquete recibido y un segundo argumento opcional: la instancia InSim que recibió ese paquete. Puede utilizar esa instancia para enviar paquetes adicionales en respuesta.

 import { InSim } from 'node-insim' ;
import { PacketType } from 'node-insim/packets' ;
import type { IS_VER } from 'node-insim/packets' ;

const inSim = new InSim ( ) ;

inSim . on ( PacketType . ISP_VER , onVersion ) ;

function onVersion ( packet : IS_VER , inSim : InSim ) {
  inSim . send (
    new IS_TINY ( {
      ReqI : 1 ,
      SubT : TinyType . TINY_PING ,
    } ) ,
  ) ;
} 

Múltiples hosts

Puede utilizar el argumento inSim en la devolución de llamada del controlador de eventos para identificar el host de origen de los paquetes recibidos, por ejemplo mediante la propiedad options.Host .

Alternativamente, el constructor de la clase InSim acepta un argumento id opcional, que también puede usarse para diferenciar las conexiones InSim.

 import { InSim } from 'node-insim' ;

const inSim1 = new InSim ( 'Host One' ) ;

inSim1 . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
  IName : 'Node InSim App' ,
} ) ;

const inSim2 = new InSim ( 'Host Two' ) ;

inSim2 . connect ( {
  Host : '127.0.0.2' ,
  Port : 30000 ,
  IName : 'Node InSim App' ,
} ) ;

inSim . on ( PacketType . ISP_VER , onVersion ) ;

function onVersion ( packet : IS_VER , inSim : InSim ) {
  console . log ( `Connected to ${ inSim . options . Host } : ${ inSim . options . Port } ` ) ;

  if ( inSim . id ) {
    console . log ( `InSim connection ID: ${ inSim . id } ` ) ;
  }
}

Codificación de cadenas

Todas las cadenas de los paquetes recibidos o enviados se convierten automáticamente de codificación LFS a Unicode y viceversa.

Si necesita acceder a la cadena codificada en LFS sin formato en un paquete recibido, use la propiedad _raw en la instancia del paquete, que contiene todas las propiedades de cadena no convertidas.

 import { InSim } from 'node-insim' ;
import { PacketType } from 'node-insim/packets' ;
import type { IS_ISM } from 'node-insim/packets' ;

const inSim = new InSim ( ) ;

inSim . on ( PacketType . ISP_ISM , ( packet : IS_ISM ) => {
  console . log ( packet . HName ) ; // UTF-8 string - ^1Drifter Team ^7★ Server
  console . log ( packet . _raw . HName ) ; // raw string - ^1Drifter Team ^7^J�� Serveru0000u0000u0000u0000
} ) ;

Cuando envía un valor de cadena Unicode en un paquete, cada carácter se codificará en la codificación LFS correcta, de modo que LFS pueda mostrar el texto en un mensaje o botón.

 import { InSim } from 'node-insim' ;
import { PacketType } from 'node-insim/packets' ;
import type { IS_MSL } from 'node-insim/packets' ;

const inSim = new InSim ( ) ;

inSim . on ( PacketType . ISP_VER , ( packet : IS_VER ) => {
  inSim . send (
    new IS_MSL ( {
      Msg : 'čau světe' , // LFS will receive: ^Eèau svìte
    } ) ,
  ) ;
} ) ;

Relé InSim

Para conectarse al servicio InSim Relay, utilice el método connectRelay() . Una vez conectado, puede enviar y recibir paquetes de retransmisión. El siguiente ejemplo demuestra cómo mostrar una lista de hosts conectados al InSim Relay:

 import { InSim } from 'node-insim' ;
import { IR_HLR , IR_HOS , PacketType , HInfo } from 'node-insim/packets' ;

inSim . connectRelay ( ) ;

inSim . on ( 'connect' , ( ) => {
  // Request a list of hosts
  inSim . send ( new IR_HLR ( ) ) ;
} ) ;

inSim . on ( PacketType . IRP_HOS , ( packet : IR_HOS ) => {
  // Log the name of each received host
  packet . Info . forEach ( ( host : HInfo ) => {
    console . log ( host . HName ) ;
  } ) ;
} ) ;

Puede encontrar más información sobre el protocolo InSim Relay en el hilo de información del cliente InSim Relay en el foro LFS.

Fuera de calibre

 import { OutGauge , OutGaugePack } from 'node-insim' ;

const outGauge = new OutGauge ( ) ;

outGauge . connect ( {
  Host : '127.0.0.1' ,
  Port : 29999 ,
} ) ;

outGauge . on ( 'packet' , ( data : OutGaugePack ) => {
  console . clear ( ) ;
  console . log ( data . RPM ) ;
} ) ;

OutSim

 import { OutSim , OutSimPack } from 'node-insim' ;

const outSim = new OutSim ( ) ;

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 OutSimPack2
  if ( ! ( data instanceof OutSimPack ) ) {
    return ;
  }

  console . clear ( ) ;
  console . log ( data . PosX ) ;
} ) ;

Depuración

Node InSim utiliza el paquete NPM debug para los registros de depuración. De forma predeterminada, Node InSim no envía ningún registro a la salida estándar.

Para habilitar el registro, utilice la variable de entorno DEBUG cuando ejecute su aplicación InSim. Todos los registros tienen el prefijo node-insim . Puede utilizar comodines para filtrar los registros que necesita.

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

Aplicaciones de ejemplo

Puede encontrar aplicaciones de ejemplo usando Node InSim en la carpeta de ejemplos.

Ejemplo
Conexión InSim	JavaScript + CJS	Mecanografiado + ESM
Conexión InSim (múltiples hosts)	JavaScript + CJS	Mecanografiado + ESM
Conexión InSim (UDP)	JavaScript + CJS	Mecanografiado + ESM
Relé InSim	JavaScript + CJS	Mecanografiado + ESM
Fuera de calibre	JavaScript + CJS	Mecanografiado + ESM
OutGauge con botones InSim	JavaScript + CJS	Mecanografiado + ESM
OutSim	JavaScript + CJS	Mecanografiado + ESM
OutSim con opciones	JavaScript + CJS	Mecanografiado + ESM

Antes de ejecutar un ejemplo, siga las instrucciones del archivo README.md de cada ejemplo.

Por ejemplo, para ejecutar el ejemplo "Conexión InSim - TypeScript", ejecute los siguientes comandos:

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

Desarrollo

Requisitos

• Nodo.js 18
• Hilo

Iniciar un servidor de desarrollo

yarn dev

Generadores de código

Al agregar nuevos paquetes InSim a la biblioteca, puede usar generadores de código integrados usando yarn generate . Creará y actualizará todos los archivos necesarios para usted.

Ejecutar pruebas unitarias

yarn test
yarn test:watch

Ejecute pruebas contra una aplicación LFS real

Para ejecutar estas pruebas, LFS debe estar ejecutándose con un puerto InSim abierto.

De forma predeterminada, las pruebas se conectan a 127.0.0.1:29999 . El host y el puerto de InSim se pueden configurar copiando .env a .env.local en el directorio lfs-test .

yarn test:lfs

Construya todas las aplicaciones de ejemplo

Este comando revisará cada aplicación en la carpeta examples/ , instalará sus dependencias y luego compilará la aplicación (solo mecanografiado).

yarn test:examples

código de pelusa

yarn lint

Código de formato

yarn format

Construcción de producción

Los archivos compilados se crearán en dist/ .

yarn build

Ejecute todas las comprobaciones a la vez

Puede ejecutar el formato de código, lint + fix, compilar y probar con el siguiente comando:

yarn check-all

---