[Home] [Downloads] [Search] [Help/forum]

MUSHclient scripting

Description of MUSHclient world function: world.UdpListen

Name UdpListen
Type Method
Summary Listens for incoming packets using the UDP protocol
Prototype long UdpListen(BSTR IP, short Port, BSTR Script);

View list of data type meanings


This lets you set up a plugin script function that will be called whenever a UDP packet arrives on the specified port.

This lets you set up a separate program which can communicate with MUSHclient by sending it UDP packets.

The maximum size message that can be received is 999 bytes. In practice, attempting to receive more than 512 bytes may fail due to fragmentation over the network. Note that UDP packets are not guaranteed to arrive, or may arrive out of order. If UDP packets are fragmented by routers, and any fragment does not arrive, then the whole packet is discarded.

UDP is best used in situations where smallish amounts of data, which are not critical that they arrive at all, or in sequence, need to be sent. An example would be something like player or mob status information, where if one packet is lost, another would arrive shortly afterwards, and the loss of a single packet would be an inconvenience, not a disaster.

To listen to messages from any address use the address "".

The address must be a dotted number, not a name (eg. "")

You can cancel a listener by calling this function (for a previously-setup port) with an empty script name.

The script must be in a plugin, and be defined to accept a single string (which is the text that arrives in the UDP packet). For example, in Lua:

function listener (s)
-- process UDP packet "s" here
end -- listener

Note: Available in version 3.56 onwards.

VBscript example
UdpListen "", 4111, "MyScript"
Jscript example
UdpListen ("", 4111, "MyScript")
Lua example
-- listening function in plugin:
function listener (s)
  ColourNote ("white", "blue", "Got UDP packet: " .. s)
end -- listener 

-- set up listener
require "check"
check (UdpListen ("", 4111, "listener"))
Returns eNotAPlugin: This must be called from a plugin
eBadParameter: The port is already in use by another plugin, or the UDP socket could not be created
eNoNameSpecified: No script name was specified
eOK: succeeded

View list of return code meanings

Introduced in version 3.56

See also ...

Function Description
GetUdpPort Find a free port for UDP listening
UdpPortList Returns an array of all the UDP ports in use by this world
UdpSend Sends a packet over the network using the UDP protocol

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.

Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes

Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes

View all functions


Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]