node insim Télécharger - node insim Téléchargement du code source

Nœud InSim

Une bibliothèque InSim pour Node.js avec prise en charge de TypeScript.

Introduction

Node InSim fournit une API JavaScript pour communiquer avec le protocole Live for Speed InSim via une connexion TCP. Après vous être connecté à un hôte LFS via un nom d'hôte et un port, vous pouvez envoyer des paquets InSim à l'hôte et recevoir des paquets entrants de l'hôte.

Toutes les structures de paquets dans Node InSim sont identiques aux structures définies dans le protocole InSim. Toutes les classes de paquets avec toutes leurs propriétés sont documentées conformément à la spécification.

Compatibilité InSim

Node InSim est compatible avec InSim version 9.

Installation

Installez le package node-insim NPM dans votre application Node.js :

npm install --save node-insim

ou si vous utilisez du fil :

yarn add node-insim

Documentation

Pour une documentation plus détaillée de l'API publique, voir https://simbroadcasts.github.io/node-insim/.

Usage

De liaison

Pour vous connecter à un hôte LFS, vous devez saisir son nom d'hôte, un port et un nom court de votre application InSim.

Le port InSim doit être configuré dans les paramètres de l'hôte LFS. Assurez-vous également que l'adresse IP publique à partir de laquelle votre application se connecte est autorisée à se connecter au port InSim de l'hôte.

Hôte unique

 import { InSim } from 'node-insim' ;

const inSim = new InSim ( ) ;

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

Plusieurs hôtes

Pour vous connecter à plusieurs hôtes à la fois, créez une nouvelle instance InSim pour chaque hôte.

 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

Par défaut, Node InSim ouvre une connexion TCP. Si vous souhaitez utiliser UDP, définissez l'option Protocol sur UDP dans la fonction 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' ,
} ) ;

Envoi de paquets

Les paquets InSim peuvent être envoyés à l'aide de la méthode send() sur l'instance de classe InSim , qui prend un seul argument : l'instance de classe de paquets.

Un moyen rapide de définir les propriétés des paquets consiste à les renseigner dans le constructeur de classe :

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

Une autre méthode consiste à attribuer chaque propriété après avoir créé l'instance :

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

Envoi de messages

La classe InSim possède des méthodes d'assistance utiles pour envoyer des messages à LFS.

Envoyer un message qui apparaîtra sur l'ordinateur local uniquement

 inSim . sendLocalMessage ( 'Local message' ) ;

Envoyer une commande

 inSim . sendMessage ( '/end' ) ;

Envoyer un message

jusqu'à 63 caractères - envoyer un paquet IS_MST
64 caractères ou plus - envoyez un paquet IS_MSX

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

Envoyer un message à une connexion spécifique par son UCID

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

Envoyer un message à un joueur spécifique par son PLID

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

Réception de paquets

La classe InSim expose une méthode on() , qui est utilisée pour écouter les paquets entrants par leur type.

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

Le rappel d'événement contient le paquet reçu et un deuxième argument facultatif : l'instance InSim qui a reçu ce paquet. Vous pouvez utiliser cette instance pour envoyer des paquets supplémentaires en réponse.

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

Plusieurs hôtes

Vous pouvez utiliser l'argument inSim dans le rappel du gestionnaire d'événements pour identifier l'hôte source des paquets reçus, par exemple par la propriété options.Host .

Alternativement, le constructeur de classe InSim accepte un argument id facultatif, qui peut également être utilisé pour distinguer les connexions 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 } ` ) ;
  }
}

Encodage de chaîne

Toutes les chaînes des paquets reçus ou envoyés sont automatiquement converties du codage LFS en Unicode et vice versa.

Si vous devez accéder à la chaîne brute codée en LFS dans un paquet reçu, utilisez la propriété _raw dans l'instance de paquet, qui contient toutes les propriétés de chaîne non converties.

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

Lorsque vous envoyez une valeur de chaîne Unicode dans un paquet, chaque caractère sera codé dans le codage LFS correct, afin que LFS puisse afficher le texte dans un message ou un bouton.

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

Relais InSim

Pour vous connecter au service InSim Relay, utilisez la méthode connectRelay() . Une fois connecté, vous pouvez envoyer et recevoir des paquets relais. L'exemple suivant montre comment afficher une liste des hôtes connectés au relais InSim :

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

Plus d'informations sur le protocole InSim Relay peuvent être trouvées dans le fil d'informations du client InSim Relay sur le forum LFS.

Hors jauge

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

HorsSim

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

Débogage

Node InSim utilise le package debug NPM pour les journaux de débogage. Par défaut, Node InSim ne génère aucun journal sur la sortie standard.

Pour activer la journalisation, utilisez la variable d'environnement DEBUG lors de l'exécution de votre application InSim. Tous les journaux portent le préfixe node-insim . Vous pouvez utiliser des caractères génériques pour filtrer les journaux dont vous avez besoin.

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

Exemples d'applications

Vous pouvez trouver des exemples d'applications utilisant Node InSim dans le dossier des exemples.

Exemple
Connexion InSim	JavaScript + CJS	TypeScript + ESM
Connexion InSim (plusieurs hôtes)	JavaScript + CJS	TypeScript + ESM
Connexion InSim (UDP)	JavaScript + CJS	TypeScript + ESM
Relais InSim	JavaScript + CJS	TypeScript + ESM
Hors jauge	JavaScript + CJS	TypeScript + ESM
OutGauge avec boutons InSim	JavaScript + CJS	TypeScript + ESM
HorsSim	JavaScript + CJS	TypeScript + ESM
OutSim avec options	JavaScript + CJS	TypeScript + ESM

Avant d'exécuter un exemple, suivez les instructions contenues dans le fichier README.md de chaque exemple.

Par exemple, pour exécuter l'exemple « Connexion InSim - TypeScript », exécutez les commandes suivantes :

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

Développement

Exigences

Node.js 18
Fil

Démarrer un serveur de développement

yarn dev

Générateurs de codes

Lors de l'ajout de nouveaux paquets InSim à la bibliothèque, vous pouvez utiliser des générateurs de code intégrés en utilisant yarn generate . Il créera et mettra à jour tous les fichiers nécessaires pour vous.

Exécuter des tests unitaires

yarn test
yarn test:watch

Exécutez des tests sur une véritable application LFS

Pour exécuter ces tests, LFS doit fonctionner avec un port InSim ouvert.

Par défaut, les tests se connectent à 127.0.0.1:29999 . L'hôte et le port InSim peuvent être configurés en copiant .env vers .env.local dans le répertoire lfs-test .

yarn test:lfs

Créer tous les exemples d'applications

Cette commande parcourra chaque application dans le dossier examples/ , installera ses dépendances, puis construira l'application (dactylographié uniquement).