Difference between revisions of "Manual:Discord Functions"

From Mudlet
Jump to navigation Jump to search
(detail what will happen when invite URL is set, was vague)
 
(48 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
<languages />
 +
{{TOC right}}
 +
{{#description2:Mudlet API documentation for functions to customize the information Mudlet displays in Discord's rich presence interface.}}
 +
=Discord Functions=
 +
 +
<translate><!--T:125--> All functions to customize the information Mudlet displays in Discord's rich presence interface. For an overview on how all of these functions tie in together, see our [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</translate>
 +
 +
<span id="getdiscorddetail"></span>
 +
 
==getDiscordDetail==
 
==getDiscordDetail==
 +
 
;getDiscordDetail()
 
;getDiscordDetail()
: Returns the text used for the Discord Rich Presence detail field. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the detail is shown.
+
: <translate><!--T:126--> Returns the text used for the Discord Rich Presence detail field. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the detail is shown.</translate>
  
See also:  
+
<translate><!--T:127--> See also: </translate>
[[#setDiscordDetail|setDiscordDetail]]
+
[[#setdiscorddetail|setDiscordDetail]]
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|3.14}}
  
;Example
+
;<translate><!--T:129--> Example</translate>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
print("Discord detail is: ".. getDiscordDetail())
+
print("<translate><!--T:130--> Discord detail is: </translate>".. getDiscordDetail())
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 +
<span id="getdiscordlargeicon"></span>
  
 
==getDiscordLargeIcon==
 
==getDiscordLargeIcon==
 +
 
;getDiscordLargeIcon()
 
;getDiscordLargeIcon()
: Returns the large icon name used for the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the large icon is shown.
+
: <translate><!--T:131--> Returns the large icon name used for the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the large icon is shown.</translate>
  
See also:  
+
<translate><!--T:132--> See also: </translate>
[[#setDiscordLargeIcon|setDiscordLargeIcon]]
+
[[#setdiscordlargeicon|setDiscordLargeIcon]]
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|3.14}}
  
;Example
+
;<translate><!--T:134--> Example</translate>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
print("Discord large icon is: ".. getDiscordLargeIcon())
+
print("<translate><!--T:135--> Discord large icon is: </translate>".. getDiscordLargeIcon())
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
 +
<span id="getdiscordlargeicontext"></span>
 
==getDiscordLargeIconText==
 
==getDiscordLargeIconText==
 +
 
;getDiscordLargeIconText()
 
;getDiscordLargeIconText()
: Returns the text used as a tooltip for the large icon in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the large icon is shown.
+
: <translate><!--T:136--> Returns the text used as a tooltip for the large icon in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the large icon is shown.</translate>
  
See also:  
+
<translate><!--T:137--> See also: </translate>
[[#setDiscordLargeIconText|setDiscordLargeIconText]]
+
[[#setdiscordlargeicontext|setDiscordLargeIconText]]
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|3.14}}
  
;Example
+
;<translate><!--T:139--> Example</translate>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
print("Discord large icon tooltip is: ".. setDiscordLargeIconText())
+
print("<translate><!--T:140--> Discord large icon tooltip is: </translate>".. getDiscordLargeIconText())
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 +
<span id="getdiscordparty"></span>
  
 
==getDiscordParty==
 
==getDiscordParty==
 +
 
;getDiscordParty()
 
;getDiscordParty()
: Returns the current and max party values used in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the the party info is shown.
+
: <translate><!--T:141--> Returns the current and max party values used in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the the party info is shown.</translate>
  
See also:  
+
<translate><!--T:142--> See also: </translate>
[[#setDiscordParty|setDiscordParty]]
+
[[#setdiscordparty|setDiscordParty]]
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|3.14}}
  
;Example
+
;<translate><!--T:144--> Example</translate>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 
local currentsize, maxsize = getDiscordParty()
 
local currentsize, maxsize = getDiscordParty()
print(string.format("Discord party: %d out of %d", currentsize, maxsize))
+
print(string.format("<translate><!--T:145--> Discord party: %d out of %d</translate>", currentsize, maxsize))
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
 +
 +
<span id="getdiscordsmallicon"></span>
 
==getDiscordSmallIcon==
 
==getDiscordSmallIcon==
 +
 
;getDiscordSmallIcon()
 
;getDiscordSmallIcon()
: Returns the small icon name used for the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the small icon is shown.
+
: <translate><!--T:146--> Returns the small icon name used for the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the small icon is shown.</translate>
  
See also:  
+
<translate><!--T:147--> See also: </translate>
[[#setDiscordSmallIcon|setDiscordSmallIcon]]
+
[[#setdiscordsmallicon|setDiscordSmallIcon]]
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|3.14}}
  
;Example
+
;<translate><!--T:149--> Example</translate>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
print("Discord small icon is: ".. getDiscordSmallIcon())
+
print("<translate><!--T:150--> Discord small icon is: </translate>".. getDiscordSmallIcon())
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
==getDiscordSmallIconText==
 
==getDiscordSmallIconText==
 +
 
;getDiscordSmallIconText()
 
;getDiscordSmallIconText()
: Returns the text used as a tooltip for the small icon in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the small icon is shown.
+
: <translate><!--T:151--> Returns the text used as a tooltip for the small icon in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the small icon is shown.</translate>
  
See also:  
+
<translate><!--T:152--> See also: </translate>
[[#setDiscordSmallIconText|setDiscordSmallIconText]]
+
[[#setdiscordsmallicontext|setDiscordSmallIconText]]
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|3.14}}
  
;Example
+
;<translate><!--T:154--> Example</translate>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
print("Discord small icon tooltip is: ".. setDiscordSmallIconText())
+
print("<translate><!--T:155--> Discord small icon tooltip is: </translate>".. getDiscordSmallIconText())
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 +
<span id="getdiscordstate"></span>
  
 
==getDiscordState==
 
==getDiscordState==
 +
 
;getDiscordState()
 
;getDiscordState()
: Returns the text used for the Discord Rich Presence state field. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the state is shown.
+
: <translate><!--T:156--> Returns the text used for the Discord Rich Presence state field. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the state is shown.</translate>
 +
 
 +
<translate><!--T:157--> See also: </translate>
 +
[[#setdiscordstate|setDiscordState]]
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:159--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
print("<translate><!--T:160--> Discord state is: </translate>".. getDiscordState())
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="getdiscordtimestamps"></span>
 +
 
 +
==getDiscordTimeStamps==
 +
 
 +
;getDiscordTimeStamps()
 +
: <translate>Returns the start/end Discord timestamps as set by [[#setDiscordElapsedStartTime|setDiscordElapsedStartTime()]] and [[#setDiscordRemainingEndTime|setDiscordRemainingEndTime()]].</translate>
 +
 
 +
<translate><!--T:157--> See also: </translate>
 +
[[#setDiscordElapsedStartTime|setDiscordElapsedStartTime]], [[#setDiscordRemainingEndTime|setDiscordRemainingEndTime]]
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:159--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
display(getDiscordTimeStamps())
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="resetdiscorddata"></span>
 +
==resetDiscordData==
 +
; resetDiscordData()
 +
 
 +
:Reset Discord Rich Presence for current profile to the Mudlet default settings.
  
See also:  
+
;See also: [[Manual:Discord_Functions#setDiscordApplicationID|setDiscordApplicationID()]], [[Manual:Discord_Functions#setDiscordDetail|setDiscordDetail()]], [[Manual:Discord_Functions#setDiscordState|setDiscordState()]]
[[#setDiscordState|setDiscordState]]
 
  
{{note}} Available since Mudlet 3.14
+
{{MudletVersion|4.14}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
print("Discord state is: ".. getDiscordState())
+
-- Use 'afk' emote in game, clear Discord party status and estimate return
 +
send("afk")
 +
resetDiscordData()
 +
setDiscordState("Back in 15")
 +
setDiscordRemainingEndTime(os.time(os.date("*t"))+(60 * 15))
 +
</syntaxhighlight>
 +
 
 +
<span id="setdiscordapplicationid"></span>
 +
==setDiscordApplicationID==
 +
 
 +
;setDiscordApplicationID(id)
 +
: <translate><!--T:161--> Set a custom Discord ID so Discord Rich Presence will show "Playing <your game>" instead of "Playing Mudlet". This function is intended for game authors. Note that you can also set it [[Standards:Discord GMCP|automatically over GMCP]], no pre-installation of scripts required. This will currently (as of Mudlet 4.9.1) bypass the Discord privacy option "Enable Lua API" on future sessions if a non-empty id is specified. Returns true if the Discord application ID is in the correct format.</translate>
 +
 
 +
<translate><!--T:162--> If you're a game author, you can register your game [https://discordapp.com/developers/applications/ over at Discord] to obtain the "client ID" to be used for this function. Once you do so, make sure to upload the games icon as an art asset under the name of <code>server-icon</code>.</translate>
 +
 
 +
<translate><!--T:163--> Mudlet calls this the Application ID to avoid confusion with Mudlet being a game client - however Discord uses both Application ID and Client ID to refer to this detail (which seems to be an 18 digit number).</translate>
 +
 
 +
;<translate><!--T:164--> Parameters </translate>
 +
* ''id:'' <translate><!--T:165--> (required) id as a string.</translate>
 +
 
 +
[[File:Mudlet Discord ApplicationID.png|thumb|right]]
 +
 
 +
<translate><!--T:166--> See also: </translate>
 +
[[#setdiscordgame|setDiscordGame]], [[#usingmudletsdiscordid|usingMudletsDiscordID]]
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:168--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
-- <translate><!--T:169--> set the ID to Mudlets own as an example</translate>
 +
setDiscordApplicationID("450571881909583884")
 +
</syntaxhighlight>
 +
 
 +
{{note}} <translate><!--T:170--> So you do not have to remember that long number you can also reset to the default Mudlet ID by calling this function without an argument:</translate>
 +
<syntaxhighlight lang="lua">
 +
setDiscordApplicationID()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
 +
<span id="setdiscorddetail"></span>
 +
 +
==setDiscordDetail==
 +
 +
;setDiscordDetail(text)
 +
: <translate><!--T:171--> Sets the text to be shown in the detail field of Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the detail is shown. Note that this will overwrite the same information set by [[#setdiscordgame|setDiscordGame()]].</translate>
 +
 +
<translate><!--T:172--> See also: </translate>
 +
[[#getdiscorddetail|getDiscordDetail]], [[#setdiscordgame|setDiscordGame]]
 +
 +
{{note}} <translate><!--T:173--> To ensure privacy, the detail will only be shown if the Lua API is enabled and the detail is not hidden.</translate>
 +
 +
{{MudletVersion|3.14}}
 +
 +
;<translate><!--T:175--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
-- <translate><!--T:176--> set detail to your character name in-game, as an example</translate>
 +
setDiscordDetail("Vadi")
 +
</syntaxhighlight>
 +
 +
 +
<span id="setdiscordelapsedstarttime"></span>
 
==setDiscordElapsedStartTime==
 
==setDiscordElapsedStartTime==
;setDiscordElapsedStartTime()
 
: Sets the time to be shown for "## elapsed" field in Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the elapsed time is shown.
 
  
{{note}} Available since Mudlet 3.14
+
;setDiscordElapsedStartTime(time)
 +
: <translate><!--T:177--> Sets the time to be shown for "## elapsed" field in Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the elapsed time is shown.</translate>
 +
 
 +
;<translate><!--T:178--> Parameters </translate>
 +
* ''time:'' <translate><!--T:179--> (required) time as a [https://en.wikipedia.org/wiki/Unix_time Unix time]. To get the current Unix time in Lua, use <code>os.time(os.date("*t"))</code>.</translate>
 +
 
 +
<translate><!--T:180--> See also: </translate>
 +
[[#setdiscordremainingendtime|setDiscordRemainingEndTime]]
 +
 
 +
{{note}} <translate><!--T:181--> To ensure privacy, the time will only be shown if the Lua API is enabled and the time is not hidden.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:183--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
-- <translate><!--T:184--> set the timer to start counting up from now:</translate>
 +
setDiscordElapsedStartTime(os.time(os.date("*t")))
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordgame"></span>
 +
==setDiscordGame==
 +
 
 +
;setDiscordGame(text)
 +
: <translate><!--T:185--> Sets the given game to be shown in the "detail" field and the game's icon as the large icon in Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the detail and large icon is shown. This is an alternative way of showing which game you're playing - a better way, if you're the game author, is to use [[Standards:Discord GMCP|GMCP]] (no pre-installation of scripts required) or [[#setdiscordapplicationid|setDiscordApplicationID()]].</translate>
 +
 
 +
<translate><!--T:186--> Currently supported games are: Achaea, Aetolia, Imperian, Luminari, Lusternia, MidMUD, Starmourn, WoTMUD. To add a new game to the list, [https://www.mudlet.org/contact/ get in touch].</translate>
 +
 
 +
<translate><!--T:187--> See also: </translate>
 +
[[#setdiscordapplicationid|setDiscordApplicationID]]
 +
 
 +
{{note}} <translate><!--T:188--> To ensure privacy, the game and icon will only be shown if the Lua API is enabled, and detail and large icon are set to show.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:190--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
setDiscordGame("WoTMUD")
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordgameurl"></span>
 +
==setDiscordGameUrl==
 +
; setDiscordGameUrl([url], [name])
 +
 
 +
:Set or clear the game Discord invite URL via Lua.  It has the same effect as the GMCP message [[Standards:Discord_GMCP#External.Discord.Info|External.Discord.Info]].
 +
 
 +
{{MudletVersion|4.14}}
 +
 
 +
{{note}} This will update the Discord button on the main toolbar, and add an option in the Help menu.
 +
 
 +
;Parameters
 +
* ''url:''
 +
: (optional) URL of Discord invite
 +
* ''name:''
 +
: (optional) Name of game
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- set the timer to start counting up from now:
+
-- set Discord invite to CoffeeMUD
setDiscordElapsedStartTime(os.time(os.date("*t")))
+
setDiscordGameUrl("https://discord.gg/HgDxtas", "CoffeeMUD")
 +
 
 +
-- remove the Discord invite
 +
setDiscordGameUrl()
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordlargeicon"></span>
 +
==setDiscordLargeIcon==
 +
 
 +
;setDiscordLargeIcon(iconName)
 +
: <translate><!--T:191--> Sets the large icon to be shown in Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference the icon is shown.</translate>
 +
 
 +
<translate><!--T:192--> Icons supported by default in Mudlet: armor, axe, backpack, bow, coin, dagger, envelope, gem-blue, gem-green, gem-red, hammer, heart, helmet, map, shield, tome, tools, wand, wood-sword ([https://opengameart.org/content/fantasy-icon-pack-by-ravenmore-0 icons credit]). To add a new icon to the list, [https://www.mudlet.org/contact/ get in touch] (the Discord limit is 150 icons).</translate>
 +
 
 +
<translate><!--T:193--> If you're a game author, you can register your own game with Discord and upload your own icons instead of using the ones registered by Mudlet, see [[#setdiscordapplicationid|setDiscordApplicationID()]].</translate>
 +
 
 +
<translate><!--T:194--> See also: </translate>
 +
[[#getdiscordlargeicon|getDiscordLargeIcon]], [[#setdiscordlargeicontext|setDiscordLargeIconText]], [[#setdiscordapplicationid|setDiscordApplicationID]]
 +
 
 +
{{note}} <translate><!--T:195--> To ensure privacy, the icon will only be shown if the Lua API is enabled and the large icon is not hidden.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:197--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
setDiscordLargeIcon("coin")
 +
setDiscordLargeIconText("<translate><!--T:198--> Fishing</translate>")
 +
setDiscordState("<translate><!--T:199--> Fishing</translate>")
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordlargeicontext"></span>
 +
==setDiscordLargeIconText==
 +
 
 +
;setDiscordLargeIconText(text)
 +
: <translate><!--T:200--> Sets the tooltip for the large icon in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference the large icon is shown.</translate>
 +
 
 +
<translate><!--T:201--> See also: </translate>
 +
[[#setdiscordlargeicon|setDiscordLargeIcon]]
 +
 
 +
{{note}} <translate><!--T:202--> To ensure privacy, the tooltip will only be shown if the Lua API is enabled, and large icon with the large icon tooltip is set to show.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:204--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
setDiscordLargeIcon("axe")
 +
setDiscordLargeIconText("<translate><!--T:205--> Killing heterics</translate>")
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordparty"></span>
 +
==setDiscordParty==
 +
 
 +
;setDiscordParty(current, max)
 +
: <translate><!--T:206--> Sets the party information the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference the party is shown.</translate>
 +
 
 +
;<translate><!--T:207--> Parameters </translate>
 +
* ''current:'' <translate><!--T:208--> (required) current party amount.</translate>
 +
* ''max:'' <translate><!--T:209--> (optional) max party amount - if not provided, then the max is set to the current amount.</translate>
 +
 
 +
<translate><!--T:210--> See also: </translate>
 +
[[#getdiscordparty|getDiscordParty]]
 +
 
 +
{{note}} <translate><!--T:211--> To ensure privacy, the party will only be shown if the Lua API is enabled and the party information is not hidden.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:213--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
-- <translate><!--T:214--> show that 5 out of 10 people are in currently in the party</translate>
 +
setDiscordParty(5, 10)
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordremainingendtime"></span>
 +
==setDiscordRemainingEndTime==
 +
 
 +
;setDiscordRemainingEndTime(time)
 +
: <translate><!--T:215--> Sets the time to be shown for "## remaining" field in Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the remaining time is shown.</translate>
 +
 
 +
;<translate><!--T:216--> Parameters </translate>
 +
* ''time:'' <translate><!--T:217--> (required) time as a [https://en.wikipedia.org/wiki/Unix_time Unix time]. To get the current Unix time in Lua, use <code>os.time(os.date("*t"))</code>.</translate>
 +
 
 +
<translate><!--T:218--> See also: </translate>
 +
[[#setdiscordelapsedstarttime|setDiscordElapsedStartTime]]
 +
 
 +
{{note}} <translate><!--T:219--> To ensure privacy, the time will only be shown if the Lua API is enabled and the time is not hidden.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:221--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
-- <translate><!--T:222--> set the timer to start counting down from an hour from now</translate>
 +
setDiscordRemainingEndTime(os.time(os.date("*t"))+(60 * 60))
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordsmallicon"></span>
 +
==setDiscordSmallIcon==
 +
 
 +
;setDiscordSmallIcon(iconName)
 +
: <translate><!--T:223--> Sets the small icon to be shown in Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference the icon is shown.</translate>
 +
 
 +
<translate><!--T:224--> Icons supported by default in Mudlet: armor, axe, backpack, bow, coin, dagger, envelope, gem-blue, gem-green, gem-red, hammer, heart, helmet, map, shield, tome, tools, wand, wood-sword ([https://opengameart.org/content/fantasy-icon-pack-by-ravenmore-0 icons credit]). To add a new icon to the list, [https://www.mudlet.org/contact/ get in touch] (the Discord limit is 150 icons).</translate>
 +
 
 +
<translate><!--T:225--> If you're a game author, you can register your own game with Discord and upload your own icons instead of using the ones registered by Mudlet, see [[#setdiscordapplicationid|setDiscordApplicationID()]].</translate>
 +
 
 +
<translate><!--T:226--> See also: </translate>
 +
[[#getdiscordsmallicon|getDiscordSmallIcon]], [[#setdiscordsmallicontext|setDiscordSmallIconText]], [[#setdiscordapplicationid|setDiscordApplicationID]]
 +
 
 +
{{note}} <translate><!--T:227--> To ensure privacy, the icon will only be shown if the Lua API is enabled and the small icon is not hidden.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:229--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
setDiscordSmallIcon("envelope")
 +
setDiscordSmallIconText("<translate><!--T:230--> Writing letters</translate>")
 +
setDiscordState("<translate><!--T:231--> Writing letters</translate>")
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordsmallicontext"></span>
 +
==setDiscordSmallIconText==
 +
 
 +
;setDiscordSmallIconText(text)
 +
: <translate><!--T:232--> Sets the tooltip for the small icon in the Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference the small icon is shown.</translate>
 +
 
 +
<translate><!--T:233--> See also: </translate>
 +
[[#setdiscordsmallicon|setDiscordSmallIcon]]
 +
 
 +
{{note}} <translate><!--T:234--> To ensure privacy, the tooltip will only be shown if the Lua API is enabled, and small icon with the small icon tooltip is set to show.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:236--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
setDiscordSmallIcon("map")
 +
setDiscordSmallIconText("<translate><!--T:237--> Exploring</translate>")
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="setdiscordstate"></span>
 +
==setDiscordState==
 +
 
 +
;setDiscordState(state)
 +
: <translate><!--T:238--> Sets the text to be shown in the state field of Discord Rich Presence. See [https://discordapp.com/developers/docs/rich-presence/how-to#updating-presence-update-presence-payload-fields Discord docs] for a handy image reference on where the state is shown.</translate>
 +
 
 +
<translate><!--T:239--> See also: </translate>
 +
[[#getdiscordstate|getDiscordState]], [[#setdiscorddetail|setDiscordDetail]]
 +
 
 +
{{note}} <translate><!--T:240--> To ensure privacy, the state will only be shown if the Lua API is enabled and the state is not hidden.</translate>
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:242--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
-- <translate><!--T:243--> set state to your current area</translate>
 +
local currentarea = getRoomArea(getPlayerRoom())
 +
local areaname = getAreaTableSwap()[currentarea]
 +
setDiscordDetail(areaname)
 +
</syntaxhighlight>
 +
 
 +
 
 +
<span id="usingmudletsdiscordid"></span>
 +
==usingMudletsDiscordID==
 +
 
 +
;usingMudletsDiscordID()
 +
: <translate><!--T:244--> Returns true if the currently playing game is set to "Mudlet". You can change this with [[#setdiscordapplicationid|setDiscordApplicationID()]].</translate>
 +
 
 +
<translate><!--T:245--> See also: </translate>
 +
[[#setdiscordapplicationid|setDiscordApplicationID]]
 +
 
 +
{{MudletVersion|3.14}}
 +
 
 +
;<translate><!--T:247--> Example</translate>
 +
<syntaxhighlight lang="lua">
 +
if usingMudletsDiscordID() then
 +
  print('<translate><!--T:248--> It is showing "Playing Mudlet" right now!</translate>')
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 13:47, 2 May 2022

Other languages:
Deutsch • ‎English • ‎Nederlands • ‎Türkçe • ‎français • ‎italiano • ‎polski • ‎suomi • ‎Ελληνικά • ‎русский • ‎العربية • ‎한국어

Discord Functions

All functions to customize the information Mudlet displays in Discord's rich presence interface. For an overview on how all of these functions tie in together, see our Discord scripting overview.

getDiscordDetail

getDiscordDetail()
Returns the text used for the Discord Rich Presence detail field. See Discord docs for a handy image reference on where the detail is shown.

See also: setDiscordDetail

Mudlet VersionAvailable in Mudlet3.14+
Example
print("Discord detail is: ".. getDiscordDetail())


getDiscordLargeIcon

getDiscordLargeIcon()
Returns the large icon name used for the Discord Rich Presence. See Discord docs for a handy image reference on where the large icon is shown.

See also: setDiscordLargeIcon

Mudlet VersionAvailable in Mudlet3.14+
Example
print("Discord large icon is: ".. getDiscordLargeIcon())


getDiscordLargeIconText

getDiscordLargeIconText()
Returns the text used as a tooltip for the large icon in the Discord Rich Presence. See Discord docs for a handy image reference on where the large icon is shown.

See also: setDiscordLargeIconText

Mudlet VersionAvailable in Mudlet3.14+
Example
print("Discord large icon tooltip is: ".. getDiscordLargeIconText())


getDiscordParty

getDiscordParty()
Returns the current and max party values used in the Discord Rich Presence. See Discord docs for a handy image reference on where the the party info is shown.

See also: setDiscordParty

Mudlet VersionAvailable in Mudlet3.14+
Example
local currentsize, maxsize = getDiscordParty()
print(string.format("Discord party: %d out of %d", currentsize, maxsize))


getDiscordSmallIcon

getDiscordSmallIcon()
Returns the small icon name used for the Discord Rich Presence. See Discord docs for a handy image reference on where the small icon is shown.

See also: setDiscordSmallIcon

Mudlet VersionAvailable in Mudlet3.14+
Example
print("Discord small icon is: ".. getDiscordSmallIcon())


getDiscordSmallIconText

getDiscordSmallIconText()
Returns the text used as a tooltip for the small icon in the Discord Rich Presence. See Discord docs for a handy image reference on where the small icon is shown.

See also: setDiscordSmallIconText

Mudlet VersionAvailable in Mudlet3.14+
Example
print("Discord small icon tooltip is: ".. getDiscordSmallIconText())


getDiscordState

getDiscordState()
Returns the text used for the Discord Rich Presence state field. See Discord docs for a handy image reference on where the state is shown.

See also: setDiscordState

Mudlet VersionAvailable in Mudlet3.14+
Example
print("Discord state is: ".. getDiscordState())


getDiscordTimeStamps

getDiscordTimeStamps()
Returns the start/end Discord timestamps as set by setDiscordElapsedStartTime() and setDiscordRemainingEndTime().

See also: setDiscordElapsedStartTime, setDiscordRemainingEndTime

Mudlet VersionAvailable in Mudlet3.14+
Example
display(getDiscordTimeStamps())


resetDiscordData

resetDiscordData()
Reset Discord Rich Presence for current profile to the Mudlet default settings.
See also
setDiscordApplicationID(), setDiscordDetail(), setDiscordState()
Mudlet VersionAvailable in Mudlet4.14+
Example
-- Use 'afk' emote in game, clear Discord party status and estimate return
send("afk")
resetDiscordData()
setDiscordState("Back in 15")
setDiscordRemainingEndTime(os.time(os.date("*t"))+(60 * 15))

setDiscordApplicationID

setDiscordApplicationID(id)
Set a custom Discord ID so Discord Rich Presence will show "Playing <your game>" instead of "Playing Mudlet". This function is intended for game authors. Note that you can also set it automatically over GMCP, no pre-installation of scripts required. This will currently (as of Mudlet 4.9.1) bypass the Discord privacy option "Enable Lua API" on future sessions if a non-empty id is specified. Returns true if the Discord application ID is in the correct format.

If you're a game author, you can register your game over at Discord to obtain the "client ID" to be used for this function. Once you do so, make sure to upload the games icon as an art asset under the name of server-icon.

Mudlet calls this the Application ID to avoid confusion with Mudlet being a game client - however Discord uses both Application ID and Client ID to refer to this detail (which seems to be an 18 digit number).

Parameters
  • id: (required) id as a string.
Mudlet Discord ApplicationID.png

See also: setDiscordGame, usingMudletsDiscordID

Mudlet VersionAvailable in Mudlet3.14+
Example
-- set the ID to Mudlets own as an example
setDiscordApplicationID("450571881909583884")

Note Note: So you do not have to remember that long number you can also reset to the default Mudlet ID by calling this function without an argument:

setDiscordApplicationID()


setDiscordDetail

setDiscordDetail(text)
Sets the text to be shown in the detail field of Discord Rich Presence. See Discord docs for a handy image reference on where the detail is shown. Note that this will overwrite the same information set by setDiscordGame().

See also: getDiscordDetail, setDiscordGame

Note Note: To ensure privacy, the detail will only be shown if the Lua API is enabled and the detail is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
-- set detail to your character name in-game, as an example
setDiscordDetail("Vadi")


setDiscordElapsedStartTime

setDiscordElapsedStartTime(time)
Sets the time to be shown for "## elapsed" field in Discord Rich Presence. See Discord docs for a handy image reference on where the elapsed time is shown.
Parameters
  • time: (required) time as a Unix time. To get the current Unix time in Lua, use os.time(os.date("*t")).

See also: setDiscordRemainingEndTime

Note Note: To ensure privacy, the time will only be shown if the Lua API is enabled and the time is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
-- set the timer to start counting up from now:
setDiscordElapsedStartTime(os.time(os.date("*t")))


setDiscordGame

setDiscordGame(text)
Sets the given game to be shown in the "detail" field and the game's icon as the large icon in Discord Rich Presence. See Discord docs for a handy image reference on where the detail and large icon is shown. This is an alternative way of showing which game you're playing - a better way, if you're the game author, is to use GMCP (no pre-installation of scripts required) or setDiscordApplicationID().

Currently supported games are: Achaea, Aetolia, Imperian, Luminari, Lusternia, MidMUD, Starmourn, WoTMUD. To add a new game to the list, get in touch.

See also: setDiscordApplicationID

Note Note: To ensure privacy, the game and icon will only be shown if the Lua API is enabled, and detail and large icon are set to show.

Mudlet VersionAvailable in Mudlet3.14+
Example
setDiscordGame("WoTMUD")


setDiscordGameUrl

setDiscordGameUrl([url], [name])
Set or clear the game Discord invite URL via Lua. It has the same effect as the GMCP message External.Discord.Info.
Mudlet VersionAvailable in Mudlet4.14+

Note Note: This will update the Discord button on the main toolbar, and add an option in the Help menu.

Parameters
  • url:
(optional) URL of Discord invite
  • name:
(optional) Name of game
Example
-- set Discord invite to CoffeeMUD
setDiscordGameUrl("https://discord.gg/HgDxtas", "CoffeeMUD")

-- remove the Discord invite
setDiscordGameUrl()


setDiscordLargeIcon

setDiscordLargeIcon(iconName)
Sets the large icon to be shown in Discord Rich Presence. See Discord docs for a handy image reference the icon is shown.

Icons supported by default in Mudlet: armor, axe, backpack, bow, coin, dagger, envelope, gem-blue, gem-green, gem-red, hammer, heart, helmet, map, shield, tome, tools, wand, wood-sword (icons credit). To add a new icon to the list, get in touch (the Discord limit is 150 icons).

If you're a game author, you can register your own game with Discord and upload your own icons instead of using the ones registered by Mudlet, see setDiscordApplicationID().

See also: getDiscordLargeIcon, setDiscordLargeIconText, setDiscordApplicationID

Note Note: To ensure privacy, the icon will only be shown if the Lua API is enabled and the large icon is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
setDiscordLargeIcon("coin")
setDiscordLargeIconText("Fishing")
setDiscordState("Fishing")


setDiscordLargeIconText

setDiscordLargeIconText(text)
Sets the tooltip for the large icon in the Discord Rich Presence. See Discord docs for a handy image reference the large icon is shown.

See also: setDiscordLargeIcon

Note Note: To ensure privacy, the tooltip will only be shown if the Lua API is enabled, and large icon with the large icon tooltip is set to show.

Mudlet VersionAvailable in Mudlet3.14+
Example
setDiscordLargeIcon("axe")
setDiscordLargeIconText("Killing heterics")


setDiscordParty

setDiscordParty(current, max)
Sets the party information the Discord Rich Presence. See Discord docs for a handy image reference the party is shown.
Parameters
  • current: (required) current party amount.
  • max: (optional) max party amount - if not provided, then the max is set to the current amount.

See also: getDiscordParty

Note Note: To ensure privacy, the party will only be shown if the Lua API is enabled and the party information is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
-- show that 5 out of 10 people are in currently in the party
setDiscordParty(5, 10)


setDiscordRemainingEndTime

setDiscordRemainingEndTime(time)
Sets the time to be shown for "## remaining" field in Discord Rich Presence. See Discord docs for a handy image reference on where the remaining time is shown.
Parameters
  • time: (required) time as a Unix time. To get the current Unix time in Lua, use os.time(os.date("*t")).

See also: setDiscordElapsedStartTime

Note Note: To ensure privacy, the time will only be shown if the Lua API is enabled and the time is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
-- set the timer to start counting down from an hour from now
setDiscordRemainingEndTime(os.time(os.date("*t"))+(60 * 60))


setDiscordSmallIcon

setDiscordSmallIcon(iconName)
Sets the small icon to be shown in Discord Rich Presence. See Discord docs for a handy image reference the icon is shown.

Icons supported by default in Mudlet: armor, axe, backpack, bow, coin, dagger, envelope, gem-blue, gem-green, gem-red, hammer, heart, helmet, map, shield, tome, tools, wand, wood-sword (icons credit). To add a new icon to the list, get in touch (the Discord limit is 150 icons).

If you're a game author, you can register your own game with Discord and upload your own icons instead of using the ones registered by Mudlet, see setDiscordApplicationID().

See also: getDiscordSmallIcon, setDiscordSmallIconText, setDiscordApplicationID

Note Note: To ensure privacy, the icon will only be shown if the Lua API is enabled and the small icon is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
setDiscordSmallIcon("envelope")
setDiscordSmallIconText("Writing letters")
setDiscordState("Writing letters")


setDiscordSmallIconText

setDiscordSmallIconText(text)
Sets the tooltip for the small icon in the Discord Rich Presence. See Discord docs for a handy image reference the small icon is shown.

See also: setDiscordSmallIcon

Note Note: To ensure privacy, the tooltip will only be shown if the Lua API is enabled, and small icon with the small icon tooltip is set to show.

Mudlet VersionAvailable in Mudlet3.14+
Example
setDiscordSmallIcon("map")
setDiscordSmallIconText("Exploring")


setDiscordState

setDiscordState(state)
Sets the text to be shown in the state field of Discord Rich Presence. See Discord docs for a handy image reference on where the state is shown.

See also: getDiscordState, setDiscordDetail

Note Note: To ensure privacy, the state will only be shown if the Lua API is enabled and the state is not hidden.

Mudlet VersionAvailable in Mudlet3.14+
Example
-- set state to your current area
local currentarea = getRoomArea(getPlayerRoom())
local areaname = getAreaTableSwap()[currentarea]
setDiscordDetail(areaname)


usingMudletsDiscordID

usingMudletsDiscordID()
Returns true if the currently playing game is set to "Mudlet". You can change this with setDiscordApplicationID().

See also: setDiscordApplicationID

Mudlet VersionAvailable in Mudlet3.14+
Example
if usingMudletsDiscordID() then
  print('It is showing "Playing Mudlet" right now!')
end