node insim Download - node insim -Quellcode herunterladen

Knoten InSim

Eine InSim-Bibliothek für Node.js mit TypeScript-Unterstützung.

Einführung

Node InSim bietet eine JavaScript-API für die Kommunikation mit dem Live for Speed InSim-Protokoll über eine TCP-Verbindung. Nachdem Sie über einen Hostnamen und einen Port eine Verbindung zu einem LFS-Host hergestellt haben, können Sie InSim-Pakete an den Host senden und eingehende Pakete vom Host empfangen.

Alle Paketstrukturen in Node InSim sind identisch mit den im InSim-Protokoll definierten Strukturen. Alle Paketklassen werden mit all ihren Eigenschaften entsprechend der Spezifikation dokumentiert.

InSim-Kompatibilität

Node InSim ist mit InSim Version 9 kompatibel.

Installation

Installieren Sie das node-insim NPM-Paket in Ihrer Node.js-Anwendung:

npm install --save node-insim

oder wenn Sie Garn verwenden:

yarn add node-insim

Dokumentation

Eine ausführlichere Dokumentation der öffentlichen API finden Sie unter https://simbroadcasts.github.io/node-insim/.

Verwendung

Verbinden

Um eine Verbindung zu einem LFS-Host herzustellen, müssen Sie dessen Hostnamen, einen Port und einen Kurznamen Ihrer InSim-Anwendung eingeben.

Der InSim-Port muss in den LFS-Hosteinstellungen konfiguriert werden. Stellen Sie außerdem sicher, dass die öffentliche IP-Adresse, von der aus Ihre Anwendung eine Verbindung herstellt, eine Verbindung zum InSim-Port des Hosts herstellen darf.

Einzelner Host

 import { InSim } from 'node-insim' ;

const inSim = new InSim ( ) ;

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

Mehrere Hosts

Um eine Verbindung zu mehreren Hosts gleichzeitig herzustellen, erstellen Sie für jeden Host eine neue InSim Instanz.

 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

Standardmäßig öffnet Node InSim eine TCP-Verbindung. Wenn Sie UDP verwenden möchten, stellen Sie in der connect die Protocol auf UDP ein.

 import { InSim } from 'node-insim' ;

const inSim = new InSim ( ) ;

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

Pakete versenden

InSim-Pakete können mit der send() Methode der InSim -Klasseninstanz gesendet werden, die ein einziges Argument benötigt – die Paketklasseninstanz.

Eine schnelle Möglichkeit, Paketeigenschaften festzulegen, besteht darin, sie im Klassenkonstruktor zu füllen:

 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 ,
  } ) ,
) ;

Eine andere Möglichkeit besteht darin, jede Eigenschaft nach dem Erstellen der Instanz zuzuweisen:

 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 ) ;

Senden von Nachrichten

Die InSim -Klasse verfügt über Hilfsmethoden, die zum Senden von Nachrichten an LFS nützlich sind.

Senden Sie eine Nachricht, die nur auf dem lokalen Computer angezeigt wird

 inSim . sendLocalMessage ( 'Local message' ) ;

Senden Sie einen Befehl

 inSim . sendMessage ( '/end' ) ;

Senden Sie eine Nachricht

bis zu 63 Zeichen – senden Sie ein IS_MST Paket
64 Zeichen oder mehr – senden Sie ein IS_MSX Paket

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

Senden Sie eine Nachricht über deren UCID an eine bestimmte Verbindung

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

Senden Sie eine Nachricht an einen bestimmten Spieler anhand seiner PLID

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

Pakete empfangen

Die InSim Klasse stellt eine on() Methode bereit, mit der eingehende Pakete anhand ihres Typs überwacht werden.

 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 } ` ) ;
}

Der Ereignisrückruf enthält das empfangene Paket und ein optionales zweites Argument – die InSim -Instanz, die dieses Paket empfangen hat. Sie können diese Instanz verwenden, um als Antwort zusätzliche Pakete zu senden.

 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 ,
    } ) ,
  ) ;
}

Mehrere Hosts

Sie können das Argument inSim im Event-Handler-Callback verwenden, um den Quellhost der empfangenen Pakete zu identifizieren, beispielsweise anhand der Eigenschaft „ options.Host .

Alternativ akzeptiert der InSim Klassenkonstruktor ein optionales id -Argument, das auch zur Unterscheidung der InSim-Verbindungen verwendet werden kann.

 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 } ` ) ;
  }
}

String-Kodierung

Alle Zeichenfolgen in empfangenen oder gesendeten Paketen werden automatisch von der LFS-Codierung in Unicode und umgekehrt konvertiert.

Wenn Sie auf die rohe LFS-codierte Zeichenfolge in einem empfangenen Paket zugreifen müssen, verwenden Sie die Eigenschaft _raw in der Paketinstanz, die alle nicht konvertierten Zeichenfolgeneigenschaften enthält.

 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
} ) ;

Wenn Sie einen Unicode-Zeichenfolgenwert in einem Paket senden, wird jedes Zeichen in der richtigen LFS-Kodierung kodiert, sodass LFS den Text in einer Nachricht oder einer Schaltfläche anzeigen kann.

 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
    } ) ,
  ) ;
} ) ;

InSim-Relais

Um eine Verbindung zum InSim Relay-Dienst herzustellen, verwenden Sie die Methode connectRelay() . Sobald die Verbindung hergestellt ist, können Sie Relay-Pakete senden und empfangen. Das folgende Beispiel zeigt, wie eine Liste der mit dem InSim Relay verbundenen Hosts angezeigt wird:

 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 ) ;
  } ) ;
} ) ;

Weitere Informationen zum InSim Relay-Protokoll finden Sie im InSim Relay-Client-Informationsthread im LFS-Forum.

OutGauge

 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 ) ;
} ) ;

Debuggen

Node InSim verwendet das debug NPM-Paket für Debug-Protokolle. Standardmäßig gibt Node InSim keine Protokolle an die Standardausgabe aus.

Um die Protokollierung zu aktivieren, verwenden Sie beim Ausführen Ihrer InSim-Anwendung die Umgebungsvariable DEBUG . Allen Protokollen wird node-insim vorangestellt. Sie können Platzhalter verwenden, um die benötigten Protokolle herauszufiltern.

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

Beispielanwendungen

Beispielanwendungen mit Node InSim finden Sie im Beispielordner.

Beispiel
InSim-Verbindung	JavaScript + CJS	TypeScript + ESM
InSim-Verbindung (mehrere Hosts)	JavaScript + CJS	TypeScript + ESM
InSim-Verbindung (UDP)	JavaScript + CJS	TypeScript + ESM
InSim-Relais	JavaScript + CJS	TypeScript + ESM
OutGauge	JavaScript + CJS	TypeScript + ESM
OutGauge mit InSim-Tasten	JavaScript + CJS	TypeScript + ESM
OutSim	JavaScript + CJS	TypeScript + ESM
OutSim mit Optionen	JavaScript + CJS	TypeScript + ESM

Bevor Sie ein Beispiel ausführen, befolgen Sie die Anweisungen in der README.md Datei jedes Beispiels.

Um beispielsweise das Beispiel „InSim-Verbindung – TypeScript“ auszuführen, führen Sie die folgenden Befehle aus:

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

Entwicklung

Anforderungen

Node.js 18
Garn

Starten Sie einen Entwicklungsserver

yarn dev

Codegeneratoren

Wenn Sie der Bibliothek neue InSim-Pakete hinzufügen, können Sie mithilfe von yarn generate integrierte Codegeneratoren verwenden. Es erstellt und aktualisiert alle erforderlichen Dateien für Sie.

Führen Sie Unit-Tests durch

yarn test
yarn test:watch

Führen Sie Tests mit einer echten LFS-Anwendung durch

Um diese Tests auszuführen, muss LFS mit geöffnetem InSim-Port ausgeführt werden.

Standardmäßig stellen die Tests eine Verbindung zu 127.0.0.1:29999 her. Der InSim-Host und -Port kann durch Kopieren von .env nach .env.local im lfs-test -Verzeichnis konfiguriert werden.