FRAP

FRAP stands for FireEngine Realtime Action Protocol. It is the network protocol which allows FireEngine 2 nodes to communicate game events to each other.

Protocol Information

FRAP operates over multicast UDP, on port 23952. It uses the UDP multicast group 224.23.95.2. FRAP is a binary protocol.

FRAP Data Model

Following is a description of the abstractions around which the FRAP protocol is designed. When we refer to the "FRAP network" below, we mean the set of machines listening on the FRAP multicast group and port, which are assumed to all be playing the same FireEngine 2-based game.

Nodes

Each node on the FRAP network can have a "client role" associated with it. The possible roles for a game are defined in xml/client-roles.xml.

At any given time, only one node may be associated with each client role.

Shared Objects

The FRAP network has a set of shared objects that exist on it. These objects represent the variables and events in this game. The shared objects for a particular game are defined in xml/global-vars.xml.

Each shared object has a string ID, which must be unique across the complete set of shared objects, regardless of type.

The allowed types of shared objects are:

• event - an event that can be triggered, with parameters defined in xml/global-vars.xml
• number - a floating-point number
• enum - an enumerated value with string keys
• bool - an enum that contains the keys "true" and "false"

Each shared object may be "hosted" by one, and only one, client role. The node currently associated with that role is the canonical location of that object, and will provide periodic updates to the rest of the network on the object's status. If no node with that client role is present on the FRAP network, the object is assumed by other nodes to have its default value.

The exception to this is events, which cannot be hosted, since they have no value.

FRAP Messages

Each datagram in the FRAP protocol can contain one or more FRAP messages.

Message Structure

Each message contains the following elements:

• Optionally:
  • the message sender's unique identity code
  • an ASCII colon character (ASCII code 58)
• a command code that identifies the message's type
• an ASCII pipe/vertical bar character (ASCII code 124)
• the message data (this varies by message type)
• an ASCII escape character (ASCII code 27)

If a message doesn't contain the optional sender clause at the beginning of the header, it is considered to be anonymous.

For example, a FRAP message might look like this:

weapons:tr|ship_hit_left

(This string would be followed by an escape character.) This message comes from the "weapons" node, and has a command code of "tr". The message data is the string "ship_hit_left".

Message Types

Following are the types of messages defined in FRAP:

Trigger

Command code: tr

The Trigger message denotes that a shared event has been triggered. The structure of the message data is as follows:

• the event's shared object ID
• an ASCII pipe/vertical bar character (ASCII code 124)
• a Pickle representation of the parameters passed to the event

Latency Test

Command code: lt

The Latency Test message is used for testing the latency, or "lag", between nodes on the network. In order for it to work correctly, the clocks of the machines must be in sync with each other.

The structure of the message consists simply of a text representation of the current UNIX timestamp as a floating point number.

Identity

Command code: id

The Identity message is used by nodes on the network to identify themselves. The body of the message is blank, because the node's identity is transmitted in the message header.

Identity Request

Command code: idr

The Identity Request message is used to request that nodes on the network send out Identity messages. The body of the message itself is blank.

Status Update

Command code: up

The Status Update message is used by nodes that are hosting shared objects. On a regular basis (say, once every 10 seconds), the node will send a Status Update message containing the current value of all its hosted shared objects.

The structure of the message is a Pickle representation of a Python dictionary object. The dictionary maps the ID string of each hosted object to a string representation of its value.

Note that when shared objects change their values, the node that initiates the value change will trigger an event that indicates the value has changed, so Status Update messages are intended as a safeguard against dropped messages rather than as a means of propagating changes to shared object values.

Status Request

Command code: sr

The Status Request message is generated when a node joins the network. This is in case the node has quit but there are other active nodes still on the network that remember the previous values of its hosted objects. The node will wait for a timeout period. During this period, other nodes are expected to respond with Status Update messages containing this data.

The structure of this message is a pipe-delimited list of shared object IDs for which the node is requesting status.