1 line
14 KiB
JSON
1 line
14 KiB
JSON
[{"id":0,"href":"/worldwideportal/docs/getting-started/","title":"Getting Started","section":"Docs","content":" Getting started with Worldwideportal # To access Worldwideportal (WWP), you need to connect to an instance of it. As Free / Open Source software, the administrator of your favourite MUD might have made an instance of WWP available for playing their MUD. If not, you can ask the MUD administrators to install it for you, or install Worldwideportal yourself. This guide will assume you already have access to a working copy.\nNote that if you are using a version provided by your MUD administrator, it might be configured to use a special layout and settings on startup - but the principles are the same.\nUsing the terminal # You interact with WWP primarily by entering commands at the terminal - either for WWP, or for the MUD. Most commands for WWP start with a # symbol, while, unless you (or the administrator of the instance you are using) configure it otherwise with aliases or Lua scripting, anything else is sent to the MUD server.\nConnecting to the server # If you are using a WWP provided by your MUD\u0026rsquo;s administrators, it might be configured to connect on load. If not, or if you want to connect to another MUD, this section can help.\nUse the #connect_mud command to connect to a MUD. Follow it with two parameters: a name of the MUD connection, so you can reference the connection later, and a URL for the WebSocket server for the MUD.\nNote: Due to browser security restrictions, it is not possible for your browser to connect directly to a MUD server\u0026rsquo;s telnet port. Instead, Worldwideportal uses a protocol called \u0026ldquo;WebSockets\u0026rdquo; for browser-MUD connections, and provides a separate component MUD administrators or interested users can run to bridge from WebSocket to telnet. You will need the WebSocket URL. WebSocket URLs start with wss://, e.g. they might look like wss://example.com/ws. If you wanted to create a MUD connection named ex to that URL, you\u0026rsquo;d type #connect_mud ex wss://example.com/ws at the prompt.\nSending commands directly to the MUD # To send a command to the MUD, just type it into the terminal and press enter. You\u0026rsquo;ll see the response on your screen.\nFor example, you might type in your username and password for a MUD (each followed by enter), and\nSending multiple commands # You can type in several commands and have them all be sent in quick succession by separating them with ;. For example, you might type n;e to go north and then east (assuming the MUD you are connected to accepts n and e as direction commands). Neither command will be sent until you press enter.\nSending repeats of the same command # If you want to repeat a command, use # followed by a number, then a space, and then your command. The command will be sent that number of times.\nFor example #5 n might be used to go north 5 places. You can combine it with ;, e.g. #5 n;#3 e to send:\nn n n n n e e e to the MUD server.\nReplaying commands # Use the up arrow to see and re-play the last command you typed. Use the up and down arrows repeatedly to navigate through the history.\nHistory is saved in your browser (last 1000 lines entered only), so it will persist even if you close the browser tab and come back later (unless you access Worldwideportal in Private Browsing / Incognito Mode, in which case it will be lost when you exit out of that mode).\nCopying and pasting # You can copy from the terminal - Ctrl Insert works best for copying, while Shift Insert works best for pasting. Some other common keypresses don\u0026rsquo;t work in all browsers.\nSetting aliases # If you often send the same command, you can set an alias - meaning that anytime you type a certain thing, instead of sending it to the MUD, it is replaced by another command (which could use ; to actually execute several commands).\nYou set an alias with #alias what-to-match commands-to-run.\nThe what-to-match is interpreted as a regular expression (regex), meaning a description of text to match that also uses special symbols to describe non-exact matches. One such special character is ^, which means to match at the start of the line only. It is a good one to start your alias regex with if you don\u0026rsquo;t want your regex to match if the text appears in the middle of a line.\nNote: Whenever you invoke a Worldwideportal command, you can wrap each argument between { and }, allowing you to include characters like ; in the argument.\nHere\u0026rsquo;s a simple example: #alias {^hi} {#echo Hello}\nAfter running this, if you type hi in the terminal, it will run the echo command (to send Hello back to your terminal).\nYou can do more advanced regular expressions. For example, suppose you wanted to add a menace command to taunt and attack an opponent, but let you specify a player and an insult. You could do something like:\n#alias {^menace (?\u0026lt;player\u0026gt;[^ ]+) (?\u0026lt;insult\u0026gt;.*)} {'$player You're $insult!;k $player} menace Rahrah a dragon-breathed hobbit-sized pea brain\nThis one is a bit more complex to understand, so let\u0026rsquo;s step through it:\n^ is at the start again. This is important, we don\u0026rsquo;t want it to match on something like You're a menace, Charlie Brown - ^ ensures it only matches if menance is at the start. The round brackets demarcate what is called \u0026ldquo;capture groups\u0026rdquo; - parts of the text you want to capture and use in the substituted commands. Capture are automatically assigned a number - $0 represents the entire matched text, $1 the first bracketed capture group, $2 the second and so on. However, it is sometimes nicer to give them a name. If you start your capture group with ?\u0026lt;name\u0026gt;, then the capture group gets named $name and can be referred to as such on the other side. The square brackets [] denote a group of characters where any character inside the brackets can match. However, when it starts with ^, it is inverted, so will match any character not in the square brackets. So [^ ] means to match any character that is not a space. The + symbol means to match one or more of what is immediately before it, instead of just one. So [^ ]+ means to match one or more characters that are not spaces. Putting it together, (?\u0026lt;player\u0026gt;[^ ]+) means to capture one or more characters that are not spaces as $player. This assumes player names can\u0026rsquo;t have spaces in your MUD! The . symbol means to match any character. The * symbol means to match zero or more of what comes before. So .* means zero or more of any character. This puts the entire end of the line into the $insult capture group. Note: Aliases are not persisted once you close the tab, but there is a way to script them to come back on every startup.\nListing aliases # Use #alias by itself to see all aliases currently set.\nDeleting aliases # Use #unalias what-to-match to remove an alias.\nSetting triggers # Aliases act on what you type into the terminal. Triggers, on the other hand, act on what a MUD sends to you. This is useful if you want to automatically take an action when something happens.\nThe syntax is #act what-to-match commands-to-run, just like aliases.\nAs an example, consider:\n#act {^The (.*) attacks you.} {\u0026quot;Hey $1, you're going to wish you hadn't done that!}\nIf the game sends The giant squid attacks you., you\u0026rsquo;ll send back:\n\u0026quot;Hey giant squid, you're going to wish you hadn't done that!\nListing triggers # Use #act by itself to see triggers that are set.\nDeleting triggers # Use #unact what-to-match to remove a trigger.\nDelays # You can schedule something to happen after a certain amount of time (in seconds, but fractional seconds allowed):\nSyntax: #delay time-to-wait commands-to-run optional-name\nExample: #delay 5 {#echo Ding!}\nGiving it a name makes it easier to cancel:\n#delay 5 {#echo Ding!} ding\n(there can only be one active delay for each name at a time, repeating it replaces it). If you don\u0026rsquo;t give it a name, it will get a numeric identifier assigned.\nListing delays # Use #delay by itself to list delays (and ticks). It will show the name of the delay first, or #number if there is no name.\nCancelling delays # Use #undelay delay-name to cancel - delay-name can be #number instead.\nTicks # Sometimes, you don\u0026rsquo;t just want something to happen once after a time period, you want it to recur. #tick does this.\nSyntax: #tick time-interval commands-to-run optional-name\nFor example, #tick 60 {#echo Cockadoodledoo!} rooster will echo a message to the terminal every 60 seconds forever until you cancel it.\nGiving it a name (rooster in the example) is optional, but makes it easier to cancel. If you don\u0026rsquo;t give it a name, it will get a numeric identifier assigned.\nListing ticks # Use #tick by itself to list ticks (and delays still active).\nCancelling ticks # Use #untick tick-name to cancel - tick-name can be #number instead.\nManaging the screen # The overall browser window can be divided up (tiled) into different frames if you want. This allows you to connect to several MUDs, or filter different messages into different windows, or to have the editor open at the same time as a MUD connection.\nReferencing a frame position on the screen # WWP has a little language for referencing a position on the screen, allowing you to act on that position.\nWhen there is only one frame, it can be referenced by an empty string - {} as an argument to the commands below. Each of the following letters can take you from {} into a further split out frame:\nl and r take you into the left or right side of a horizontally split screen. t and b take you into the top or bottom side of a vertically split screen. You put them together into a string to reference a position, for example brt would mean go to the bottom frame of a vertical split, and within that expect a horizontal split - going to the the right side of that, and then in that expecting another vertical split, and take the top. This way, you can uniquely reference any frame on the screen.\nSplitting the screen vertically # To initiate a vertical split, use #vsplit frame-to-split new-frame-number.\nFor example, if you only have one frame up, #vsplit {} 2 will split the screen in half vertically. Note that you can use any frame number that hasn\u0026rsquo;t been used (1 is the initially created default frame), and it will be created for you.\nAliases and so on are not shared between frames, so you have to recreate them in the other frame.\nSplitting the screen horizontally # To initiate a horizontal split, use #hsplit frame-to-split new-frame-number.\nFor example, if you only have one frame up, #hsplit {} 2 will split the screen in half horizontally.\nRejoining frames # Use #panel_merge frame-path-to-merge. The second panel (right or bottom) will be hidden, leaving the left or top. e.g. to get rid of the top-level split, #panel_merge {}.\nResizing frames # You can use the mouse to drag the separator between frames / panels to a size that suits you.\nManaging scripts # Aliases, triggers, and so on only exist for the current session. But what if you want to build something really advanced and save it? That is where scripts come in. Scripts are saved in your browser and persist when you come back to the same Worldwideportal instance after closing the tab (unless you use Private Browsing / Incognito, in which case they are generally lost between sessions).\nScripts are written in Lua.\nOpening the editor # Type #editor to get into the editor, where you can manage scripts. This will temporarily put the frame you are in into editor mode (split first if you want to have the editor and your MUD open at the same time).\nThe script browser and the editor area # On the left is the script browser, showing all your scripts. On the right is the editor area - a text editor for the currently selected script.\nBy default, there is only one script, called init.lua. This is a special script which you can\u0026rsquo;t delete, and which gets run when you start your client.\nAt the top of the script browser is a bar with actions you can take in the editor. You can run a script now in the current frame (Ctrl+Enter also works), create a new script, or exit out of the editor mode.\nGetting out of the editor # You can press escape, or use the back arrow in the bar at the top of the script browser (right hand side).\nEditing a script # Click on the script name. It should highlight. If you tab in to the script browser, you can also use the up and down arrows to select a script.\nOnce it is selected, head over to the editor area on the right hand side and you can type in text to it. Press Ctrl+Enter to test out the script to see if it works. If there is an error, it appears at the top of the screen in a bar (and will disappear if you run a script with no errors).\nNote: There is no need to save - scripts are immediately saved in your browser as you edit them. If you make a mistake and mess up your script, you can undo (only until you leave the editor or switch scripts though) with Ctrl+Z.\nCreating a script # You can create a script by clicking on the plus icon at the top of the script browser. You\u0026rsquo;ll need to enter a name for it. It will start off empty.\nDeleting a script # You can delete a script by clicking on the bin icon alongside the script. You can never delete init.lua, but if you don\u0026rsquo;t want anything to happen at startup, you can delete all the text from the file. You\u0026rsquo;ll need to confirm a deletion, but then it is irreversible.\nWriting Lua code to control the client # Scripts should contain Lua code, which is different to the syntax of a normal command. You can, however, submit a normal command from Lua by using commands.command(\u0026quot;command to send\u0026quot;), e.g. commands.command(\u0026quot;n\u0026quot;).\nIn general, the global commands table gives you access to all commands - and you call them with parameters using Lua syntax as needed.\nFor example, to set an alias, you can use commands.alias(\u0026quot;^hi\u0026quot;, \u0026quot;#echo Hello\u0026quot;) from Lua.\nYou can register new global commands as well, e.g.\ncommands.mycustomcommand = function(x) commands.echo(\u0026#34;You called mycustomcommand with argument \u0026#34;..x); end Don\u0026rsquo;t forget to run your Lua code before expecting it to work!\nUnlike aliases, commands are global - they will work in any frame.\nTip: When setting aliases or triggers to call into Lua code, the most robust way is to register a new custom command, and make the alias or trigger submit that command.\nIf you want to write a comment in your Lua code, use -- to make the rest of the line a comment, or --[[ to open a comment block that runs until you close it with --]].\n"}] |