Script function
world.UdpListen
Read about scripting
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
Description
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 "0.0.0.0".
The address must be a dotted number, not a name (eg. "10.0.0.8")
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
Available in MUSHclient version 3.56 onwards.
VBscript example
UdpListen "0.0.0.0", 4111, "MyScript"
Jscript example
UdpListen ("0.0.0.0", 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 ("0.0.0.0", 4111, "listener"))
Return value
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
See Also ...
Functions
(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
(Help topic: function=UdpListen)