### Getting Started

# 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.

Note 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.

## Using 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.

## Connecting to the server #

If you are using a WWP provided by your MUD’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.

Use 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.

Note: Due to browser security restrictions, it is not possible for your browser to connect directly to a MUD server’s telnet port. Instead, Worldwideportal uses a protocol called “WebSockets” 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’d type `#connect_mud ex wss://example.com/ws` at the prompt.

## Sending commands directly to the MUD #

To send a command to the MUD, just type it into the terminal and press enter. You’ll see the response on your screen.

For example, you might type in your username and password for a MUD (each followed by enter), and

## Sending 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.

## Sending 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.

For example `#5 n` might be used to go north 5 places. You can combine it with `;`, e.g. `#5 n;#3 e` to send:

    n
    n
    n
    n
    n
    e
    e
    e

to the MUD server.

## Replaying 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.

History 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).

## Copying 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’t work in all browsers.

## Setting 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).

You set an alias with `#alias what-to-match commands-to-run`.

The 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’t want your regex to match if the text appears in the middle of a line.

Note: Whenever you invoke a Worldwideportal command, you can wrap each argument between `{` and `}`, allowing you to include characters like `;` in the argument.

Here’s a simple example: `#alias {^hi} {#echo Hello}`

After running this, if you type `hi` in the terminal, it will run the echo command (to send Hello back to your terminal).

You 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:

`#alias {^menace (?<player>[^ ]+) (?<insult>.*)} {'$player You're $insult!;k $player}` `menace Rahrah a dragon-breathed hobbit-sized pea brain`

This one is a bit more complex to understand, so let’s step through it:

- `^` is at the start again. This is important, we don’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 “capture groups” - 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 `?<name>`, 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, `(?<player>[^ ]+)` means to capture one or more characters that are not spaces as `$player`. This assumes player names can’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.

### Listing aliases #

Use `#alias` by itself to see all aliases currently set.

### Deleting aliases #

Use `#unalias what-to-match` to remove an alias.

## Setting 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.

The syntax is `#act what-to-match commands-to-run`, just like aliases.

As an example, consider:

`#act {^The (.*) attacks you.} {"Hey $1, you're going to wish you hadn't done that!}`

If the game sends `The giant squid attacks you.`, you’ll send back:

`"Hey giant squid, you're going to wish you hadn't done that!`

### Listing triggers #

Use `#act` by itself to see triggers that are set.

### Deleting triggers #

Use `#unact what-to-match` to remove a trigger.

## Delays #

You can schedule something to happen after a certain amount of time (in seconds, but fractional seconds allowed):

Syntax: `#delay time-to-wait commands-to-run optional-name`

Example: `#delay 5 {#echo Ding!}`

Giving it a name makes it easier to cancel:

`#delay 5 {#echo Ding!} ding`

(there can only be one active delay for each name at a time, repeating it replaces it). If you don’t give it a name, it will get a numeric identifier assigned.

### Listing 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.

### Cancelling delays #

Use `#undelay delay-name` to cancel - delay-name can be `#number` instead.

## Ticks #

Sometimes, you don’t just want something to happen once after a time period, you want it to recur. `#tick` does this.

Syntax: `#tick time-interval commands-to-run optional-name`

For example, `#tick 60 {#echo Cockadoodledoo!} rooster` will echo a message to the terminal every 60 seconds forever until you cancel it.

Giving it a name (rooster in the example) is optional, but makes it easier to cancel. If you don’t give it a name, it will get a numeric identifier assigned.

### Listing ticks #

Use `#tick` by itself to list ticks (and delays still active).

### Cancelling ticks #

Use `#untick tick-name` to cancel - tick-name can be `#number` instead.

## Managing 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.

### Referencing 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.

When 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:

- `l` 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.

### Splitting the screen vertically #

To initiate a vertical split, use `#vsplit frame-to-split new-frame-number`.

For 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’t been used (1 is the initially created default frame), and it will be created for you.

Aliases and so on are not shared between frames, so you have to recreate them in the other frame.

### Splitting the screen horizontally #

To initiate a horizontal split, use `#hsplit frame-to-split new-frame-number`.

For example, if you only have one frame up, `#hsplit {} 2` will split the screen in half horizontally.

### Rejoining 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 {}`.

### Resizing frames #

You can use the mouse to drag the separator between frames / panels to a size that suits you.

## Managing 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).

Scripts are written in Lua.

### Opening 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).

### The 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.

By default, there is only one script, called `init.lua`. This is a special script which you can’t delete, and which gets run when you start your client.

At 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.

### Getting 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).

### Editing 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.

Once 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).

Note: 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.

### Creating a script #

You can create a script by clicking on the plus icon at the top of the script browser. You’ll need to enter a name for it. It will start off empty.

### Deleting 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’t want anything to happen at startup, you can delete all the text from the file. You’ll need to confirm a deletion, but then it is irreversible.

### Writing 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("command to send")`, e.g. `commands.command("n")`.

In general, the global `commands` table gives you access to all commands - and you call them with parameters using Lua syntax as needed.

For example, to set an alias, you can use `commands.alias("^hi", "#echo Hello")` from Lua.

You can register new global commands as well, e.g.

    commands.mycustomcommand = function(x)
      commands.echo("You called mycustomcommand with argument "..x);
    end

Don’t forget to run your Lua code before expecting it to work!

Unlike aliases, commands are global - they will work in any frame.

Tip: 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.

If 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 `--]]`.