Message

Definition

A message is the basic communications unit for the Second Life world. Messages are used to pass serialized information about almost every part of the system back and forth between two hosts on a network, through connections known as circuits.

There are many hundreds of messages in the Second Life message system. A list of them is available at Category:Messages.

Message Format

Messages are defined in the Message Template. They follow the format:

{
	[Message Name] [Message Frequency] [Message ID] [Message Trust Level] [Message Encoding]
	{
		[Block 1 Name]		[Block 1 Quantity]
		{	[Block 1 Parameter 1 Name]		[Block 1 Parameter 1 Type]	}
		{	[Block 2 Parameter 2 Name]		[Block 2 Parameter 2 Type]	}
                [...]
	}
        [...]
	{
		[Block n Name]		[Block n Quantity]
		{	[Block n Parameter 1 Name]		[Block n Parameter 1 Type]	}
                [...]
	}
}

For example

{
	TestMessage Low 1 NotTrusted Zerocoded
	{
		TestBlock1		Single
		{	Test1		U32	}
	}
	{
		NeighborBlock		Multiple		4
		{	Test0		U32	}
		{	Test1		U32	}
		{	Test2		U32	}
	}
}

Preamble

The preamble contains information about the message as a whole.

• Name
  • Values: [string]
  • Name of the message. Follows C variable naming restrictions.
• Frequency
  • Values: High|Medium|Low|Fixed [U32]
  • Determines whether the message ID is 8, 16, or 32 bits. There can be 254 messages in the High or Medium, 32K in Low. A message with a "Fixed" frequency defines its own ID and is considered to be a signal. For more information, see Packet Layout
• Trust Level
  • Values: Trusted|NotTrusted
  • Denotes the minimum trust level needed for the circuit between the sender and receiver in order for the message to send successfully. For more information, see Circuits.
• Compression
  • Values: Unencoded|Zerocoded
  • Zerocoding will attempt to compress sequences of zeros in the message in order to reduce network load. If there is no major size difference after the compression, it is discarded and the message is sent uncompressed.

Blocks

Blocks are delimiters for groups of data in a message.

• Name
  • Values: [string]
  • Name of the block. Follows C variable naming restrictions.
• Quantity
  • Values: Single|Multiple [U8]|Variable
  • Determines how many blocks are contained in the message. "Multiple" means a static number of blocks in every message, and is followed by an 8 bit number to tell how many times the block is repeated, "Variable" lets the sender specify the number of blocks on sending (also an 8 bit number).

Variables

Variables contain the data sent with the message

• Name
  • Values: [string]
  • Name of the variable. Follows C variable naming restrictions.
• Type
  • Values: Null|Fixed [U32]|Variable [U32]|U8|U16|U32|U64|S8|S16|S32|S64|F32|F64
  • Values Cont: LLVector3|LLVector3d|LLVector4|LLQuaternion|LLUUID|BOOL|IPADDR|IPPORT|U16Vec3|U16Quat|S16Array
  • The type of the variable. "Fixed"/"Variable" are used to denote sizes for things like blobs.

Data Types

• Null - no data, 0 bytes wide
• Fixed - byte array, interpreted depending on packet type, width determined in message definition
• Variable 1 - first byte determines number of bytes that follow (U8)
• Variable 2 - first two bytes determine number of bytes that follow (U16, big-endian in UDP Packet Layouts)
• U8 - unsigned byte, 1 byte wide
• U16 - unsigned short, 2 bytes wide (little-endian in UDP packet layouts)
• U32 - unsigned int, 4 bytes wide (little-endian in UDP packet layouts)
• U64 - unsigned long, 8 bytes wide (little-endian in UDP packet layouts)
• S8 - signed byte, 1 byte wide
• S16 - signed short, 2 bytes wide (little-endian in UDP packet layouts)
• S32 - signed int, 4 bytes wide (little-endian in UDP packet layouts)
• S64 - signed long, 8 bytes wide (little-endian in UDP packet layouts)
• F32 - float, 4 bytes wide
• F64 - double, 8 bytes wide
• LLVector3 - triplet of floats, 12 bytes wide
• LLVector3d - triplet of doubles, 24 bytes wide
• LLVector4 - quad of floats, 16 bytes wide
• LLQuaternion - because it's always a unit quaternion, transmitted in messages as a triplet of floats, 12 bytes wide (represented in memory as a quad of floats, 16 bytes wide)
• LLUUID - Universal ID, 16 bytes wide
• BOOL - 0 or 1, 1 byte wide
• IPADDR - IP Address, one place per byte, 4 bytes wide
• IPPORT - IP Port, two bytes wide
• U16Vec3 - not used
• U16Quat - not used
• S16Array - not used