InSim

Here are several examples of using the library, more in-depth documentation is currently being written.

Hello, InSim!

The simplest pyinsim program. We initialize InSim and send the message 'Hello, InSim!' to the game chat.

# Import the pyinsim module.
import pyinsim

# Initialize InSim on the specified host and port.
insim = pyinsim.insim('127.0.0.1', 29999, Admin='')

# Send message 'Hello, InSim!' to the host.
insim.sendm('Hello, InSim!')

# Run the pyinsim system.
pyinsim.run()

Note that we are calling sendm(msg) to send the message, this is a convenience method that pyinsim provides. We could also have written this code in a slightly more verbose way.

import pyinsim

insim = pyinsim.insim('127.0.0.1', 29999, Admin='')

# Create new MST message packet with the Msg 'Hello, InSim!'
mst = pyinsim.IS_MST(Msg='Hello, InSim!')

# Send the packet to InSim.
insim.sendp(mst)

pyinsim.run()

We create a packet object which we then send to InSim. This also demonstrates that packets in pyinsim are just normal Python objects, there is nothing special about them. As this pattern of sending packets is so common, pyinsim contains another convenience method for doing so.

import pyinsim

insim = pyinsim.insim('127.0.0.1', 29999, Admin='')

# Send message packet to InSim.
insim.send(pyinsim.ISP_MST, Msg='Hello, InSim!')

pyinsim.run()

Events

We have seen how to send simple packets, but what about receiving them? pyinsim uses a simple event system for handling incoming packets.

import pyinsim

# Function to handle MSO packet event.
def message_out(insim, mso):
     # Print the MSO message to the stdout.
    print mso.Msg

insim = pyinsim.insim('127.0.0.1', 29999, Admin='')

# Bind event for MSO packet.
insim.bind(pyinsim.ISP_MSO, message_out)

pyinsim.run()

Each time a MSO packet is received the event will be raised. The first event parameter is a reference to the object that raised the event, the second parameter is the packet object itself. There are also several other high-level events which pyinsim can raise, these are:
  • EVT_INIT - InSim is initialized
  • EVT_CLOSE - InSim has closed
  • EVT_ERROR - An error has occurred
  • EVT_ALL - Special event to bind all packets
  • EVT_OUTSIM - Bind an OutSim packet
  • EVT_OUTGAUGE - Bind an OutGauge packet
  • EVT_TIMEOUT - A UDP connection with LFS has timed out
Here is an example of using these events.

import pyinsim

# Function called for INIT event.
def init(insim):
    print 'InSim is initialized!'

# Function called for CLOSE event.
def closed(insim):
    print 'InSim has closed!'

insim = pyinsim.insim('127.0.0.1', 29999, Admin='')

# Bind events
insim.bind(pyinsim.EVT_INIT, init)
insim.bind(pyinsim.EVT_CLOSE, closed)

pyinsim.run()

InSim Relay

pyinsim has full InSim Relay support, which allows you to connect to the LFS Relay Server and request data about any online hosts.

import pyinsim

def new_connection(relay, ncn):
    # Print out connection name.
    print 'Connection:', ncn.UName

# Initialize InSim relay and select the specified host.
relay = pyinsim.relay(HName='My Host Name')

# Bind events.
relay.bind(pyinsim.ISP_NCN, new_connection)

# Request connection list from host.
relay.send(pyinsim.ISP_TINY, ReqI=255, SubT=pyinsim.TINY_NCN)

# Run pyinsim.
pyinsim.run()

Last edited Apr 12, 2011 at 11:28 PM by AlexMcBride, version 3

Comments

No comments yet.