Note: You should read InSim.txt for an overview of how InSim works. PIE
handles a lot of things for you, but you need to know the difference between
your PLIDs and your UCIDs, which packets you can send/receive, what
instructions you can send, for a few examples.
Note for advanced programmers: please forgive the following
over-explanations, simplifications, terminology shortcuts and outright lies.
PIE is for all levels of coding ability, right down to the
only-just-beginning - the tutorials have to start there and build up! There
is a quick reference if you want a shortcut to the goodies.
// [Introduction] /////////////////////////////////////////////////////////////
PIE is designed to be give easy access to InSim functionality with the PHP
programming language (ver 7.2, CLI mode). It takes care of connection to InSim
(and optionally OutSim and OutGauge) and maintaining the connection, and calls
a user-defined function on receipt of any packet. It can be used to connect to
an LFS client (local mode) or an LFS server (host mode) and comes with some
basic commands and debugging.
PIE is a commandline executable that reads a PHP file (refered to as a PIE
script) and optionally a text configuration file. PIE then uses the settings
provided, or defaults, to initiate a connection to InSim. Once connected, PIE
will wake from sleep at the specified frequency to run a 'tick'. During this
tick, PIE will process any incoming packets, call any pending callback
functions, and return to sleep. PIE runs at between 5 and 50 ticks per second,
default 20.
PIE scripts consist of PHP functions that are called by PIE as appropriate,
such as at startup, on receipt of a packet, at a pre-specified time, etc.
There are functions available to do common tasks such as sending packets,
speaking to chat, etc., and a PIE object provides constantly-updated InSim
information and a data store.
Functions that are called on receipt of an InSim packet are called with a
parameter which consists of all the packet data, unpacked into an associative
array. Some packets with combined values have additional indexes for the
separated values, and all text fields have been made safe for windows (0 byte
stripped, raw SkinID bytes converted to SkinID text string).
PIE will attempt to run at the specified frequency by sleeping less after
longer tick, but you must still take care about the length of time it takes
your code to run. You have plenty of time to communicate with an online
database, for example, as long as your queries do not take longer to complete
than the length of your tick interval. PIE will not be able to process
packets, call callback functions etc., whilst waiting for script code. In
extreme cases, the InSim connection may timeout or the buffer may overflow.
// [Tutorial Overview] ////////////////////////////////////////////////////////
1) Hello world: (Connecting to local client; Sending messages to chat; Local chat; Shutting down PIE)
2) Hello player: (Accepting packets; Connecting to hosts; PIE cfg files)
3) Race start message: (Sending packets; Sending buttons; Callbacks)
4) Random lights: (PIE stored values; Debugging)
5) No-repair reset: (PIE commands; PIE data)
6) Headsup: (OutGauge; File logging)
7) Object info: (Layout objects; Button clicks; Multiple buttons)
handles a lot of things for you, but you need to know the difference between
your PLIDs and your UCIDs, which packets you can send/receive, what
instructions you can send, for a few examples.
Note for advanced programmers: please forgive the following
over-explanations, simplifications, terminology shortcuts and outright lies.
PIE is for all levels of coding ability, right down to the
only-just-beginning - the tutorials have to start there and build up! There
is a quick reference if you want a shortcut to the goodies.
// [Introduction] /////////////////////////////////////////////////////////////
PIE is designed to be give easy access to InSim functionality with the PHP
programming language (ver 7.2, CLI mode). It takes care of connection to InSim
(and optionally OutSim and OutGauge) and maintaining the connection, and calls
a user-defined function on receipt of any packet. It can be used to connect to
an LFS client (local mode) or an LFS server (host mode) and comes with some
basic commands and debugging.
PIE is a commandline executable that reads a PHP file (refered to as a PIE
script) and optionally a text configuration file. PIE then uses the settings
provided, or defaults, to initiate a connection to InSim. Once connected, PIE
will wake from sleep at the specified frequency to run a 'tick'. During this
tick, PIE will process any incoming packets, call any pending callback
functions, and return to sleep. PIE runs at between 5 and 50 ticks per second,
default 20.
PIE scripts consist of PHP functions that are called by PIE as appropriate,
such as at startup, on receipt of a packet, at a pre-specified time, etc.
There are functions available to do common tasks such as sending packets,
speaking to chat, etc., and a PIE object provides constantly-updated InSim
information and a data store.
Functions that are called on receipt of an InSim packet are called with a
parameter which consists of all the packet data, unpacked into an associative
array. Some packets with combined values have additional indexes for the
separated values, and all text fields have been made safe for windows (0 byte
stripped, raw SkinID bytes converted to SkinID text string).
PIE will attempt to run at the specified frequency by sleeping less after
longer tick, but you must still take care about the length of time it takes
your code to run. You have plenty of time to communicate with an online
database, for example, as long as your queries do not take longer to complete
than the length of your tick interval. PIE will not be able to process
packets, call callback functions etc., whilst waiting for script code. In
extreme cases, the InSim connection may timeout or the buffer may overflow.
// [Tutorial Overview] ////////////////////////////////////////////////////////
1) Hello world: (Connecting to local client; Sending messages to chat; Local chat; Shutting down PIE)
2) Hello player: (Accepting packets; Connecting to hosts; PIE cfg files)
3) Race start message: (Sending packets; Sending buttons; Callbacks)
4) Random lights: (PIE stored values; Debugging)
5) No-repair reset: (PIE commands; PIE data)
6) Headsup: (OutGauge; File logging)
7) Object info: (Layout objects; Button clicks; Multiple buttons)