From 372126a92a7ebf027af29a2387c0539cc5977e5e Mon Sep 17 00:00:00 2001 From: Griatch Date: Fri, 24 Mar 2023 23:47:28 +0100 Subject: [PATCH] More cleanup of MXP doc page --- docs/source/Concepts/Clickable-Links.md | 63 ++++++++++++++++--------- 1 file changed, 42 insertions(+), 21 deletions(-) diff --git a/docs/source/Concepts/Clickable-Links.md b/docs/source/Concepts/Clickable-Links.md index 2a616473a5..86241c6e67 100644 --- a/docs/source/Concepts/Clickable-Links.md +++ b/docs/source/Concepts/Clickable-Links.md @@ -1,48 +1,69 @@ # Clickable links -Evennia supports clickable links for clients that supports it. This marks certain text so it can be clicked by a mouse and either trigger a given Evennia command, or open a URL in an external web browser. To support clickable links, Evennia requires the webclient or an third-party telnet client with [MXP](http://www.zuggsoft.com/zmud/mxp.htm) support (*Note: Evennia only supports clickable links, no other MXP features*). +Evennia allows for clickable links in text for clients that supports it. This marks certain text so it can be clicked by a mouse and either trigger a given Evennia command, or open a URL in an external web browser. To see clickable links, the player must use the Evennia webclient or a third-party telnet client with [MXP](http://www.zuggsoft.com/zmud/mxp.htm) support (*Note: Evennia only supports clickable links, no other MXP features*). -- `|lc` to start the link, by defining the command to execute. -- `|lu` to start the link, by defining the URL to open. -- `|lt` to continue with the text to show to the user (the link text). -- `|le` to end the link text and the link definition. +Users with clients lacking MXP support will only see the link as normal text. -All elements must appear in exactly this order to make a valid link. For example, if you have an object with a description +```{important} +By default, clickable links can _not_ be added from in-game. Trying to do so will have the link come back as normal text. This is a security measure. See [Settings](#settings) for more information. +``` + +## Click to run a command + +``` +|lc command |lt text |le +``` + +Example: ``` "If you go |lcnorth|ltto the north|le you will find a cottage." ``` -This will display as "If you go __to the north__ you will find a cottage." where clicking the link will execute the command `north`. If the client does not support clickable links, only the link text will be shown. +This will display as "If you go __to the north__ you will find a cottage." where clicking the link will execute the command `north`. -## MXP can be exploited - -By default MXP links are only available _from strings provided in code_ (or via a [batch script](../Components/Batch-Processors.md)). You _cannot_ create MXP links from inside the game - the result will not come out as clickable. - -This is a security measure. Consider if a user were able to enter clickable links in their description, like this: +## Click to open an url in a web browser ``` -|lc give 1000 gold to Bandit |ltClick here to read my backstory! |le +|lu url |lt text |le ``` -This would be executed by the poor player clicking the link, resulting in them paying 1000 gold to the bandit. - -If you think this risk is acceptable, you can remove this protection by adding the following to your settings: +Example: ``` -MXP_OUTGOING_ONLY = False +"Omnious |luhttps://mycoolsounds.com/chanting"|ltchanting sounds|le are coming from beyond the door. ``` -## Other settings +This will show as "Omnious **chanting sounds** are coming from beyond the door", where clicking the link will open the url in a browser if the client supports doing so. -Enable / disable MXP overall (default is shown) +## Settings + +Enable / disable MXP overall (enabled by default). ``` MXP_ENABLED = True ``` -Make help entries have clickable topics in supported clients +By default help entries have clickable topics. ``` HELP_CLICKABLE_TOPICS = True -``` \ No newline at end of file +``` + +By default clickable links are only available _from strings provided in code_ (or via a [batch script](../Components/Batch-Processors.md)). You _cannot_ create clickable links from inside the game - the result will not come out as clickable. + +This is a security measure. Consider if a user were able to enter clickable links in their description, like this: + +``` +|lc give 1000 gold to Bandit |ltClick here to read my backstory!|le +``` + +This would be executed by the poor player clicking the link, resulting in them paying 1000 gold to the bandit. + +This is controlled by the following default setting: + +``` +MXP_OUTGOING_ONLY = True +``` + +Only disable this protection if you know your game cannot be exploited in this way. \ No newline at end of file