InSim

InSim

InSim er en protokol, der gør det muligt for et eksternt program at kommunikere med Live for hastighed. Det giver dig mulighed for at oprette en sokkelforbindelse med spillet og til at sende og modtage pakker med data. InSim-protokollen beskriver, hvordan hver af disse pakker er formateret, og ethvert programmeringssprog, der kan oprette en netværksforbindelse og sende og modtage strenge af binære data, kan interface med det.

den officielle dokumentation er inkluderet i filen InSim.tekst, findes i mappen Spil doc. Den består af en C++ header-fil, der indeholder definitionen for hver pakke, samt kommentarer fra Scavenia om, hvordan hver skal bruges. Dokumentationen her er tænkt som et supplement til denne fil.

UDP vs TCP

InSim understøtter både UDP og TCP-forbindelser. I UDP-tilstand kan der kun oprettes en enkelt forbindelse, men der kan oprettes op til otte forbindelser til spillet i TCP. Uanset om det er tilsluttet i TCP eller UDP, er det muligt at angive en separat UDP-stik til modtagelse af bilpositionsopdateringer, såsom IS_MCI og IS_NLP.

InSim eksempel

hvordan du går i gang med at oprette en InSim-forbindelse afhænger naturligvis af hvilket programmeringssprog du bruger, men her forsøger vi at dokumentere processen med nogle eksempler fra det populære Python-programmeringssprog. Som nævnt ovenfor kan ethvert sprog, der er i stand til at oprette en stikkontakt, bruges til at interface med LFS, men princippet forbliver det samme uanset.

oprettelse af en forbindelse

først og fremmest skal vi etablere en sokkelforbindelse med spillet, i dette tilfælde i TCP.

# Import Python's socket module.import socket# Initialise the socket in TCP mode. sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)# Connect to LFS.sock.connect(('localhost', 29999))

initialisering af InSim

efter oprettelse af forbindelsen skal vi initialisere InSim-systemet ved at sende IS_ISI-pakken. Før vi kan gøre dette, skal vi dog først intitailse InSim inden for LFS selv. For at gøre dette skal du starte spillet og indtaste chatkommandoen “/insim 29999”. Det anvendte portnummer kan være en hvilken som helst gyldig port, men 29999 har generelt en tendens til at være den accepterede standard.

her er definitionen for IS_ISI-pakken fra InSim.TST.

struct IS_ISI // InSim Init - packet to initialise the InSim system{byteSize;// 44byteType;// ISP_ISIbyteReqI;// If non-zero LFS will send an IS_VER packetbyteZero;// 0wordUDPPort;// Port for UDP replies from LFS (0 to 65535)wordFlags;// Bit flags for options (see below)byteSp0;// 0bytePrefix;// Special host message prefix characterwordInterval;// Time in ms between NLP or MCI (0 = none)charAdmin;// Admin password (if set in LFS)charIName;// A short name for your program};

hver InSim-pakke begynder med en overskrift, der består af 4 byte. Den første byte er størrelsen på pakken efterfulgt af pakketypen fra isp_-tællingen og derefter rekvisitionen (står for anmodning-Id). Når der fremsættes en anmodning til LFS, skal værdien af rekvisitionen indstilles til ikke-nul, hvorved LFS svarer med den samme værdi, der er angivet i rekvisitionen for den anmodede pakke. Endelig varierer den fjerde byte afhængigt af den pågældende pakke, som i dette tilfælde er tom.

som du kan se, indeholder is_isi-pakken forskellige indstillinger og flag, der bruges, når InSim-systemet initialiseres. Vi skal pakke disse data i en binær formateret streng for at sende den til LFS.

# Import Python's struct module, which allows us to pack and unpack strings.import struct# Pack the IS_ISI data into a string.isi = struct.pack('BBBBHHBcH16s16s', 44, # Size 1, # Type 1, # ReqI 0, # Zero 0, # UDPPort 0, # Flags 0, # Sp0 ' ', # Prefix 0, # Interval 'password', # Admin 'MyProgram',) # IName# Send the string to InSimsock.send(isi)

modtagelse af Data

efter oprettelse af forbindelsen og initialisering af InSim skal vi derefter opsætte pakken modtage loop. Da data i TCP-tilstand sendes som en konstant strøm af data, kan flere pakker ankomme i et enkelt modtagelsesopkald, og nogle pakker kan ankomme ufuldstændige. Det betyder, at vi skal gemme alle indgående data i en buffer og derefter læse hver pakke ud, når vi er sikre på, at den er færdig.

# We use a string as the buffer.buffer = ''while True: # Receive up to 1024 bytes of data. data = sock.recv(1024) # If no data is received the connection has closed. if data: # Append received data onto the buffer. buffer += data # Loop through each completed packet in the buffer. The first byte of # each packet is the packet size, so check that the length of the # buffer is at least the size of the first packet. while len(buffer) > 0 and len(buffer) > ord(buffer): # Copy the packet from the buffer. packet = buffer)] # Remove the packet from the buffer. buffer = buffer):] # The packet is now complete! :) # doSomethingWithPacket(packet) else: break# Release the socket.sock.close()

udpakning af pakker

når vi har modtaget pakkedataene som en binær formateret streng, skal vi derefter pakke disse data ud i et format, der er nyttigt for os. I vores tidligere eksempel, da vi sendte IS_ISI-initailiseringspakken, satte vi rekvisitionen til ikke-nul, hvilket betyder, at LFS reagerede med en IS_VER-versionspakke, men vi gjorde ikke noget med det. Lad os først se på definitionen for IS_VER-pakken fra InSim.TST.

struct IS_VER // VERsion{byteSize;// 20byteType;// ISP_VERSIONbyteReqI;// ReqI as received in the request packetbyteZero;charVersion;// LFS version, e.g. 0.3GcharProduct;// Product : DEMO or S1wordInSimVer;// InSim Version : increased when InSim packets change};

lad os nu se på, hvordan vi ville udpakke disse data i Python.

# Import Python's struct module.import struct# Unpack the binary formatted packet data into the values we need.size, type, reqi, zero, version, product, insimver = struct.unpack('BBBB8s6sH', packet)# Check the InSim version.if insimver != 4: print 'Invalid InSim version!' sock.close()

Keep Alive

for at holde forbindelsen åben sender LFS en “keep alive” – pakke hvert 30.sekund. Denne pakke er en IS_TINY med en SubT (undertype) af TINY_NONE. Vi skal svare på denne pakke hver gang den modtages for at forhindre, at forbindelsen med InSim går ud.

# Some constants.ISP_TINY = 3TINY_NONE = 0# Check the packet type.if ord(packet) == ISP_TINY: # Unpack the packet data. tiny = struct.unpack('BBBB', packet) # Check the SubT. if tiny == TINY_NONE: # Send the keep alive packet back to LFS. sock.send(packet)

yderligere eksempler

du kan se det fulde eksempel på denne kode såvel som andre på insim-eksemplerne.

InSim-biblioteker

selvfølgelig som det gamle ordsprog går, bør du ikke forsøge at genopfinde hjulet (medmindre du forsøger at lære mere om hjul), og der er flere modne InSim-biblioteker til rådighed til brug i din egen kode.

InSim Reference

her er et forsøg på at henvise til den komplette InSim-protokol.