Pocket MUD Pro Documentation

General Usage

Pocket MUD Pro is a MUD client for the iPhone which allows you to connect to your favorite MUD on the go.

Connecting To A MUD

When you first launch Pocket MUD Pro, you will see a large list of some of the most popular MUD's in existence. To connect to a MUD, simply tap on the MUD's name and it will instantly connect you to the game world.

Disconnecting From A MUD

If you wish to disconnect from a MUD or have been disconnected and want to return to the MUD list screen, tap the eject icon in the bottom right-hand corner of the MUD view. It will ask you to confirm and then bring you back to the MUD list.

Adding A MUD

To add a new MUD, tap the "+" button in the upper right hand corner of the main MUD list screen

Changing a MUD's Settings

To modify information about a MUD including name, address, port, triggers, and aliases, tap the blue ">" icon next to the MUD in the MUD list view.

Favorite MUDs

The 'big list' of MUDs can be quite annoying and difficult to navigate at times. That's why we have implemented a favorites list which is quickly accessible by tapping the "Favorites" button at the top of the MUD list. To add a MUD as a favorite, open up it's settings and tap the slider which corresponds to "Favorite". Then tap "Save". The MUD should now appear in your favorites list

Autostart

Some players might want to skip the MUD selection altogether. This might be the case if you really only play one MUD. If you toggle "auto start" to on in the MUD settings and tap "save", that MUD will immediately be launched on startup of Pocket MUD Pro.

Triggers

Triggers are a mechanism which allow you to respond to certain text in the MUD and update accordingly. Triggers could be used for tasks as simple as auto-logging in to your favorite MUD or as complex as creating a fully automated character. When a trigger fires, it can run lua code. Tap here to read more about lua.

The following section will show you how to use triggers inside of Pocket MUD Pro as well as show you the full trigger API

Adding A New Trigger

To add a trigger, navigate to the MUD settings of the MUD you are creating a trigger for. Then tap "Add" under the row marked "Triggers". Triggers require the following information:

Matching MUD Text

Before a trigger can fire, it must match some specified text sent by the MUD. You can just enter in plain text here OR use regular expressions. Here are some example patterns:

thy name, adventurer?

This will match Aardwolf's request for you to enter your character name when logging in. You could use this text to create an auto-login trigger

hit by a s.*

This will match anything where something starting with "s" hit you. (You were hit by a snake).

Pocket MUD Pro triggers also support captures which get injected into your lua script. See captures for more info.

Lua Basics And Trigger API

When a trigger or alias fires, it executes lua code. There are quite a few things you can do inside of this code. Since you have the full lua language inside, the possibilities become endless. Here is a look at all of the Pocket MUD Pro specific API calls you are able to make

send: This function sends text to the MUD.

send("kill rat")
would send the text "kill rat" to the server.

echo: This function prints the text to the screen but doesn't send it to the server.

echo("YOU MUST EAT")
would print "YOU MUST EAT" to your MUD View.

gag: This function suppresses the output of the text passed in. You might use this in order to shorten long descriptions or silence a character who talks too much. When using the gag command, you also have access to a variable called line which is the text line that contained the match.

gag(line)
will suppress the output of the entire line containing the match.
gag("welcome to the game")
will suppress only the text "welcome to the game".

replace: Replaces some specified text with some other text. In fact, the gag command is simply replace(line,"")

replace("rats","dogs")
will replace all occurrences of the word "rats" with the word "dogs".

prompt: This will replace the prompt text. The prompt sits just above your text entry view and is persistent even when the MUD text updates.

prompt(health .. "hp " .. magic .. "mp")
This will update the prompt to show your character's HP and MP. It will look like 530hp 45mp. You could have grabbed these values from a capture.

trigger_enable: Enables a specific trigger. This command uses the trigger (case sensitive) as an identifier.

trigger_enable("Rat Bot")
Would enable a trigger named "Rat Bot"

trigger_disabled: Disables a specific trigger. This command uses the trigger (case sensitive) name as an identifier.

trigger_enable("Rat Bot")
Would disable a trigger named "Rat Bot"

timer: Runs some specified lua code after a given amount of time (in seconds).

timer(5,"send(\"kill rat\")")
Would send the command "kill rat" after 5 seconds. Note that quotes for the parameters of the send command must be escaped with \ 's or it will fail to parse properly.

sound: Plays a sound from a given package. Although you can select single sounds to play when a trigger fires, you can also use this command to programmatically invoke a sound.

sound("Basic","bell.caf")
would play the bell sound from the Basic package when the trigger fires.

bar: Creates html text to render a status bar (for health, mana, etc). Use this in conjunction with prompt.
Syntax: bar([value],[max],[label],[color],[width])

prompt(bar(10,20,"HP","Red",13))
would display a red bar labeled HP 50% full with a length of 13.

Capturing MUD Text

If you specify text in your match area, it will be injected into your lua code using the matches lua table. In lua, arrays/tables are 1 indexed and the element at position 1 is always equal to the entire line that matched the pattern, the next indices will contain each of the captures. Here is an example:

Pattern: \[(.*)/(.*)hp

This could be used to get your current and max HP in the Aardwolf MUD which has a prompt that looks like [123/400hp 22/234mp]. You could then use these values in your MUD like this:

current_hp = matches[2]
max_hp = matches[3]
percent = current_hp/max_hp

prompt("Health: " .. percent .. "%")
         

The matches array will contain the following values:
matches[1] = [123/400hp
matches[2] = 123
matches[3] = 400

Aliases

Aliases allow you to create your own custom commands. You may either create a command to send a string of commands back to the mud OR create a command that runs a script (such as enabling or disabling a trigger).

Aliases can be accessed from any MUD settings screen, by tapping the Add button under the Aliases heading.

Creating A Basic Alias

Here are the parts of an alias:

Example:

Command: ll
Text: ON
Code: look north; look south; look east; look west

This command would cause you to look in all of the main directions when typing the ll command.

Capturing Text

As you did with triggers, you can also capture text in your alias commands. Captured text will show up using %num where num is the number of variables you add to the end of the command. For example

Command: ll
Text: ON
Code: look %1; look %2;

Now you can type "ll north west" and it will look north and then west.