User Messages

From GMod Wiki

Contents 1 What are they 2 How do they work? 3 Examples 3.1 Contentless message (Simplest) 3.2 Fixed structure message (Simple) 3.3 Variable length message (Complex) 4 Additional Notes 5 See Also

What are they

User messages are probably the most efficient way of sending data to the client from the server. They allow multiple parameters to be sent in their binary form.

How do they work?

• The server begins the operation by calling umsg.Start with the name of the user message.
• Data is filled in by using the umsg.Float, umsg.Long, umsg.Entity functions (for a full list, see here).
• Once the message has been filled in, the server then calls umsg.End. This causes the server to actually send the message.
• The message is received on the client machine. This will call usermessage.IncomingMessage on the client, which will look for the hook that's specified by the user message name.
• The client will then call the hook, and the client should unpack the message using the bf_read object that is passed to the function.

• WARNING. WARNING. WARNING. Usermessages must be sent in a specific order, or they will fail. And if you're just sending it to one player, don't use a filter, just put the player object as the second argument on the server.

Examples

Contentless message (Simplest)

user messages does not necessarly need to have a content, this type of message is very useful simply to trigger a specific response from the client (like opening a derma menu)

On the client:

 
function my_message_hook( um )
    Msg( "The message has been received!" )
end
usermessage.Hook("my_message", my_message_hook)
 

On the server:

 
umsg.Start("my_message") -- Not passing a filter or player will automatically send it to all players
umsg.End()
 

Client Output:

 
The message has been received!
 

Fixed structure message (Simple)

On the client:

function my_message_hook( um )
    Msg( "The text is " .. um:ReadString() .. "\n" )
    Msg( "The number is " .. um:ReadLong() .. "\n" )
    Msg( "The entity " .. tostring( um:ReadEntity() ) .. "\n" )
end
usermessage.Hook("my_message", my_message_hook)

On the server:

 
local rp = RecipientFilter()     -- Grab a CRecipientFilter object
local plys = player.GetAll()     -- Grab all the players on the server
rp:AddPlayer(plys[1])            -- Add the first two players on the server
rp:AddPlayer(plys[2])            -- Add the first two players on the server
 
umsg.Start("my_message", rp)
    umsg.String( "Hello World! The answer to everything is")
    umsg.Long( 42 )
    umsg.Entity( ents.FindByClass("prop_physics")[1] )
umsg.End()
 

Client Output:

The text is: Hello World! The answer to everything is
The number is: 42
The entity is: [prop_physics][86]

Variable length message (Complex)

On the client:

function my_variable_message_hook( um )
    local num_lines = um:ReadLong()                                -- Read number of lines.
    Msg( "Number of lines: " .. num_lines .. "\n")
    for i=1, num_lines do
        Msg( "Line " .. i .. ": \"" .. um:ReadString() .. "\"\n" ) -- Print each line
    end
end
usermessage.Hook("my_variable_message", my_variable_message_hook)

On the server:

 
function SendText( ply, txt )
    umsg.Start("my_variable_message", ply) -- If you only want to send a usermessage to one player, don't bother with a filter
        umsg.Long( #txt )            -- Send the number of lines
        for i=1, #txt do
            umsg.String( txt[i] )    -- Send each line in turn
        end
    umsg.End()                       -- Dispatch message!
end
 
local text_to_send = {
   "The quick brown fox",
   "Jumped over the lazy dog",
   "and fell in to the fire",
   "and died. The end."
}
SendText( player.GetAll()[1], text_to_send ) -- Send the text to the first player on the server
 

Client Output:

Number of lines: 4
Line 1: "The quick brown fox"
Line 2: "Jumped over the lazy dog"
Line 3: "and fell in to the fire"
Line 4: "and died. The end."
 

Additional Notes

• User Messages must be read in the order they were received, regardless of their type.
• SendUserMessage is a convenient way to send user messages.

See Also

• usermessage Library
• umsg Library
• RecipientFilters
• Object