Difference between revisions of "Manual:Networking Functions"

From Mudlet
Jump to navigation Jump to search
(→‎sendGMCP: Clarified that many GMCP messages are sent automatically by the server, and sendGMCP is not needed for those cases.)
(→‎Networking Functions: updated syntax highlighting)
Line 18: Line 18:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
connectToServer("midnightsun2.org", 3000)
 
connectToServer("midnightsun2.org", 3000)
  
 
-- save to disk so these parameters are used next time when opening the profile
 
-- save to disk so these parameters are used next time when opening the profile
 
connectToServer("midnightsun2.org", 3000, true)
 
connectToServer("midnightsun2.org", 3000, true)
</lua>
+
</syntaxhighlight>
  
 
===disconnect===
 
===disconnect===
Line 31: Line 31:
 
: See also: [[Manual:Networking_Functions#reconnect|reconnect()]]
 
: See also: [[Manual:Networking_Functions#reconnect|reconnect()]]
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
disconnect()
 
disconnect()
</lua>
+
</syntaxhighlight>
  
 
===downloadFile===
 
===downloadFile===
Line 42: Line 42:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
-- just download a file and save it in our profile folder
 
-- just download a file and save it in our profile folder
 
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"
 
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"
Line 48: Line 48:
 
downloadFile(saveto, url)
 
downloadFile(saveto, url)
 
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")
 
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")
</lua>
+
</syntaxhighlight>
  
 
A more advanced example that downloads a webpage, reads it, and prints a result from it:
 
A more advanced example that downloads a webpage, reads it, and prints a result from it:
<lua>
+
<syntaxhighlight lang="lua">
 
-- create a function to parse the downloaded webpage and display a result
 
-- create a function to parse the downloaded webpage and display a result
 
function downloaded_file(_, filename)
 
function downloaded_file(_, filename)
Line 73: Line 73:
 
-- download a list of fake users for a demo
 
-- download a list of fake users for a demo
 
downloadFile(getMudletHomeDir().."/achaea-who-count.html", "https://www.achaea.com/game/who")
 
downloadFile(getMudletHomeDir().."/achaea-who-count.html", "https://www.achaea.com/game/who")
</lua>
+
</syntaxhighlight>
  
 
Result should look like this:
 
Result should look like this:
Line 93: Line 93:
  
 
;Example:
 
;Example:
<lua>
+
<syntaxhighlight lang="lua">
 
openUrl("http://google.com")
 
openUrl("http://google.com")
 
openUrl("www.mudlet.org")
 
openUrl("www.mudlet.org")
</lua>
+
</syntaxhighlight>
  
 
===reconnect===
 
===reconnect===
Line 103: Line 103:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
-- you could trigger this on a log out message to reconnect, if you'd like
 
-- you could trigger this on a log out message to reconnect, if you'd like
 
reconnect()
 
reconnect()
</lua>
+
</syntaxhighlight>
  
 
===sendAll===
 
===sendAll===
Line 113: Line 113:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
-- instead of using many send() calls, you can use one sendAll
 
-- instead of using many send() calls, you can use one sendAll
 
sendAll("outr paint", "outr canvas", "paint canvas")
 
sendAll("outr paint", "outr canvas", "paint canvas")
 
-- can also have the commands not be echoed
 
-- can also have the commands not be echoed
 
sendAll("hi", "bye", false)
 
sendAll("hi", "bye", false)
</lua>
+
</syntaxhighlight>
  
 
===sendGMCP===
 
===sendGMCP===
Line 128: Line 128:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
--This would send "Core.KeepAlive" to the server, which resets the timeout
 
--This would send "Core.KeepAlive" to the server, which resets the timeout
 
sendGMCP("Core.KeepAlive")
 
sendGMCP("Core.KeepAlive")
Line 144: Line 144:
  
 
sendGMCP([[Char.Skills.Get { "group": "woodlore", "name": "hide"}]])
 
sendGMCP([[Char.Skills.Get { "group": "woodlore", "name": "hide"}]])
</lua>
+
</syntaxhighlight>
  
 
===sendMSDP===
 
===sendMSDP===
Line 159: Line 159:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
-- ask for a list of commands, lists, and reportable variables that the server supports
 
-- ask for a list of commands, lists, and reportable variables that the server supports
 
sendMSDP("LIST", "COMMANDS", "LISTS", "REPORTABLE_VARIABLES")
 
sendMSDP("LIST", "COMMANDS", "LISTS", "REPORTABLE_VARIABLES")
Line 168: Line 168:
 
-- or on your health and location
 
-- or on your health and location
 
sendMSDP("REPORT", "HEALTH", "ROOM_VNUM", "ROOM_NAME")
 
sendMSDP("REPORT", "HEALTH", "ROOM_VNUM", "ROOM_NAME")
</lua>
+
</syntaxhighlight>
  
 
===sendIrc===
 
===sendIrc===
Line 181: Line 181:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
--This would send "hello from Mudlet!" to the channel #mudlet on freenode.net
 
--This would send "hello from Mudlet!" to the channel #mudlet on freenode.net
 
sendIrc("#mudlet", "hello from Mudlet!")
 
sendIrc("#mudlet", "hello from Mudlet!")
 
--This would send "identify password" in a private message to Nickserv on freenode.net
 
--This would send "identify password" in a private message to Nickserv on freenode.net
 
sendIrc("Nickserv", "identify password")
 
sendIrc("Nickserv", "identify password")
</lua>
+
</syntaxhighlight>
  
 
===sendTelnetChannel102===
 
===sendTelnetChannel102===
Line 193: Line 193:
  
 
;Example
 
;Example
<lua>
+
<syntaxhighlight lang="lua">
 
-- turn prompt flags on:
 
-- turn prompt flags on:
 
sendTelnetChannel102("\52\1")
 
sendTelnetChannel102("\52\1")
Line 199: Line 199:
 
-- turn prompt flags off:
 
-- turn prompt flags off:
 
sendTelnetChannel102("\52\2")
 
sendTelnetChannel102("\52\2")
</lua>
+
</syntaxhighlight>
  
  

Revision as of 04:14, 29 June 2017

Networking Functions

A collection of functions for managing networking.

connectToServer

connectToServer(host, port, save)
Connects to the server and port.
Parameters
  • host:
Server domain or IP address.
  • port:
Servers port.
  • save:
(optional, boolean) if provided, saves the new connection parameters in the profile so they'll be used next time you open it.

Note Note: save is available in Mudlet 3.2+.

Example
connectToServer("midnightsun2.org", 3000)

-- save to disk so these parameters are used next time when opening the profile
connectToServer("midnightsun2.org", 3000, true)

disconnect

disconnect()
Disconnects you from the game right away. Note that this will not properly log you out of the game - use an ingame command for that. Such commands vary, but typically QUIT will work.
See also: reconnect()
Example
disconnect()

downloadFile

downloadFile(saveto, url)
Downloads the resource at the given url into the saveto location on disk. This does not pause the script until the file is downloaded - instead, it lets it continue right away and downloads in the background. When a download is finished, the sysDownloadDone event is raised (with the saveto location as the argument), or when a download fails, the sysDownloadError event is raised with the reason for failure. You may call downloadFile multiple times and have multiple downloads going on at once - but they aren’t guaranteed to be downloaded in the same order that you started them in.

Note Note: Since Mudlet 3.0, https downloads are supported and the actual url that was used for the download is returned - useful in case of redirects.

Example
-- just download a file and save it in our profile folder
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"
local url = "http://www.mudlet.org/wp-content/files/dark-theme-mudlet.zip"
downloadFile(saveto, url)
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")

A more advanced example that downloads a webpage, reads it, and prints a result from it:

-- create a function to parse the downloaded webpage and display a result
function downloaded_file(_, filename)
  -- is the file that downloaded ours?
  if not filename:find("achaea-who-count.html", 1, true) then return end

  -- read the contents of the webpage in
  local f, s, webpage = io.open(filename)
  if f then webpage = f:read("*a"); io.close(f) end
  -- delete the file on disk, don't clutter
  os.remove(filename)

  -- parse our downloaded file for the player count
  local pc = webpage:match([[Total: (%d+) players online]])
  display("Achaea has "..tostring(pc).." players on right now.")
end

-- register our function to run on the event that something was downloaded
registerAnonymousEventHandler("sysDownloadDone", "downloaded_file")

-- download a list of fake users for a demo
downloadFile(getMudletHomeDir().."/achaea-who-count.html", "https://www.achaea.com/game/who")

Result should look like this:

DownloadFile demo.png.

getNetworkLatency

getNetworkLatency()
Returns the last measured response time between the sent command and the server reply in seconds - e.g. 0.058 (=58 milliseconds lag) or 0.309 (=309 milliseconds). This is the N: number you see bottom-right of Mudlet.

Also known as server lag.

Example

Need example

openUrl

openUrl (url)
Opens the default OS browser for the given URL.
Example
openUrl("http://google.com")
openUrl("www.mudlet.org")

reconnect

reconnect()
Force-reconnects (so if you're connected, it'll disconnect) you to the game.
Example
-- you could trigger this on a log out message to reconnect, if you'd like
reconnect()

sendAll

sendAll(list of things to send, [echo back or not])
send()'s a list of things to the game. If you'd like the commands not to be shown, include false at the end.
Example
-- instead of using many send() calls, you can use one sendAll
sendAll("outr paint", "outr canvas", "paint canvas")
-- can also have the commands not be echoed
sendAll("hi", "bye", false)

sendGMCP

sendGMCP(command)
Sends a GMCP message to the server. The IRE document on GMCP has information about what can be sent, and what tables it will use, etcetera.
Note that this function is rarely used in practice. For most GMCP modules, the messages are automatically sent by the server when a relevant event happens in the game. For example, LOOKing in your room prompts the server to send the room description and contents, as well as the GMCP message gmcp.Room. A call to sendGMCP would not be required in this case.
See Also: GMCP Scripting
Example
--This would send "Core.KeepAlive" to the server, which resets the timeout
sendGMCP("Core.KeepAlive")

--This would send a request for the server to send an update to the gmcp.Char.Skills.Groups table.
sendGMCP("Char.Skills.Get {}")

--This would send a request for the server to send a list of the skills in the 
--vision group to the gmcp.Char.Skills.List table.

sendGMCP([[Char.Skills.Get { "group": "vision"}]])

--And finally, this would send a request for the server to send the info for 
--hide in the woodlore group to the gmcp.Char.Skills.Info table

sendGMCP([[Char.Skills.Get { "group": "woodlore", "name": "hide"}]])

sendMSDP

sendMSDP(variable[, value][, value...])
Sends a MSDP message to the server.
Parameters
  • variable:
The variable, in MSDP terms, that you want to request from the server.
  • value:
The variables value that you want to request. You can request more than one value at a time.
See Also: MSDP support in Mudlet, Mud Server Data Protocol specification
Example
-- ask for a list of commands, lists, and reportable variables that the server supports
sendMSDP("LIST", "COMMANDS", "LISTS", "REPORTABLE_VARIABLES")

-- ask the server to start keeping you up to date on your health
sendMSDP("REPORT", "HEALTH")

-- or on your health and location
sendMSDP("REPORT", "HEALTH", "ROOM_VNUM", "ROOM_NAME")

sendIrc

sendIrc(channel, message)
Sends a message to an IRC channel or person. You must have the IRC window open, and if speaking to a channel, be joined in that channel. IRC currently only works on the freenode network and password-protected channels aren't supported.
Parameters
  • channel:
The channel to send the message to. Can be #<channelname> to send to a channel, or <person name> to send to a person. Passed as a string.
  • message:
The message to send. Passed as a string.
Example
--This would send "hello from Mudlet!" to the channel #mudlet on freenode.net
sendIrc("#mudlet", "hello from Mudlet!")
--This would send "identify password" in a private message to Nickserv on freenode.net
sendIrc("Nickserv", "identify password")

sendTelnetChannel102

sendTelnetChannel102(msg)
Sends a message via the 102 subchannel back to the MUD (that's used in Aardwolf). The msg is in a two byte format - see `help telopts` in Aardwolf on how that works.
Example
-- turn prompt flags on:
sendTelnetChannel102("\52\1")

-- turn prompt flags off:
sendTelnetChannel102("\52\2")