Project

Profile

Help

Alias » History » Sprint/Milestone 4

Vincent Le Goff, 12/02/2016 09:47 PM

1 1 Vincent Le Goff
h1. Aliases in CocoMUD
2 1 Vincent Le Goff
3 1 Vincent Le Goff
Aliases are a special feature of MUD clients that can be used to shorten commands.  An alias is itself a command, but instead of being sent to the server as is, it is first analyzed by the client, modified and extended if necessary.  Some aliases don't leave the client at all.
4 1 Vincent Le Goff
5 1 Vincent Le Goff
This document will introduce the concept of aliases and explain how to create and manage them.
6 1 Vincent Le Goff
7 2 Vincent Le Goff
{{toc}}
8 2 Vincent Le Goff
9 1 Vincent Le Goff
h2. Adding an alias
10 1 Vincent Le Goff
11 1 Vincent Le Goff
You can create an alias using the interface or through the [[#SharpScript-syntax|SharpScript syntax]].  The interface being easier at first glance, it will be explained in first.
12 1 Vincent Le Goff
13 1 Vincent Le Goff
h3. Through the dialog box
14 1 Vincent Le Goff
15 1 Vincent Le Goff
In the menu bar, select Game -> Aliases.  You will find yourself in a dialog listing the current aliases for this world.  Note that aliases are usually created in a world, being shared by characters.  This will change in future versions.
16 1 Vincent Le Goff
17 1 Vincent Le Goff
In this dialog, you can add, edit or remove aliases.  By default, the list of alias will most likely be empty, so you can select *Add* to add one.
18 1 Vincent Le Goff
19 1 Vincent Le Goff
You will then have to choose an alias name.  This is the command you want to create, basically.  In this example, we're going to create a "tts" alias that enables/disables the text-to-speech in the client.
20 1 Vincent Le Goff
21 1 Vincent Le Goff
Enter "tts" in this field.  When you press Tab, you will be presented with a list of actions to be performed when you type this command.  For instance, you may want the "rs" alias to send two commands at the MUD server:  "reload" and "shoot".  In this case, you would select the action named "send one or more commands to the server".
22 1 Vincent Le Goff
23 1 Vincent Le Goff
In our example, we'll select "Enable/Disable TTS", since that's what we want to do when we type "tts" in the client.  Tab again and click the *Add action* button.
24 1 Vincent Le Goff
25 1 Vincent Le Goff
You will be prompted with a dialog asking you to review parameters to this action.  For this action, there is none, so you can press "OK" to add the action.
26 1 Vincent Le Goff
27 1 Vincent Le Goff
The new action has been added.  The cursor will be put in the list of current actions linked to this alias.  You can link an alias with several actions (even with the same action several times, to play several sounds, for instance, although it might not be very useful).
28 1 Vincent Le Goff
29 4 Vincent Le Goff
The list of current actions may be a bit scary.  It contains summarized information.  If you have selected the "Enable/Disable TTS", it will create the action @#tts@.  That's a shortcut, a notation used by the SharpScript engine, and you don't need to worry much about it, unless you want to play with the scripting system in CocoMUD.
30 4 Vincent Le Goff
31 1 Vincent Le Goff
To summarize the dialog when you add or edit an alias, you will find:
32 1 Vincent Le Goff
33 4 Vincent Le Goff
* The alias' name (a text edit).
34 4 Vincent Le Goff
* A list of actions that are currently linked with this alias.  If the alias isn't linked with any action, the list won't appear.
35 4 Vincent Le Goff
* A button to edit the selected line of action.  If the alias isn't linked with any action, the button won't appear.
36 4 Vincent Le Goff
* A button to remove this line of action from the alias.  If the alias isn't linked with any action, the button won't appear.
37 4 Vincent Le Goff
* A list of actions that can be linked to this alias.
38 1 Vincent Le Goff
* The button to add this action.
39 1 Vincent Le Goff
40 1 Vincent Le Goff
You should get accustomed to this dialog, as it will be present for most configuration involving SharpScript.  It is, in fact, the SharpScript editor that do not ask you to edit the configuration file by hand.  You will find more examples in the rest of the documentation.
41 1 Vincent Le Goff
42 1 Vincent Le Goff
To save the alias, don't forget to select "OK" several times, until the dialog box is closed.
43 1 Vincent Le Goff
44 1 Vincent Le Goff
If you then type "tts" in the client, you should see (and hear):
45 1 Vincent Le Goff
46 1 Vincent Le Goff
<pre>
47 1 Vincent Le Goff
TTS off.
48 1 Vincent Le Goff
</pre>
49 1 Vincent Le Goff
50 1 Vincent Le Goff
Type it again to switch it on.  The text-to-speech will be disabled or enabled using this alias.
51 1 Vincent Le Goff
52 1 Vincent Le Goff
h3. SharpScript syntax
53 1 Vincent Le Goff
54 1 Vincent Le Goff
You can also add an alias by editing your configuration file and adding it there.  This solution might be preferred by some.
55 1 Vincent Le Goff
56 1 Vincent Le Goff
Open your configuration file for this world.  You will find it in the "worlds" directory.  Select the directory containing your world, then the "config.set" file.  You can open it with a small editor like notepad.
57 1 Vincent Le Goff
58 1 Vincent Le Goff
To add an alias, use the @#alias@ action with two parameters:
59 1 Vincent Le Goff
60 1 Vincent Le Goff
* The alias' name.
61 1 Vincent Le Goff
* The alias' actions to be performed.
62 1 Vincent Le Goff
63 1 Vincent Le Goff
If you want to create a "tts" alias that will enable or disable the text-to-speech, add in your file the following line:
64 1 Vincent Le Goff
65 1 Vincent Le Goff
<pre>
66 1 Vincent Le Goff
#alias tts #tts
67 1 Vincent Le Goff
</pre>
68 1 Vincent Le Goff
69 1 Vincent Le Goff
If you have several actions, don't hesitate to describe the alias on several lines:
70 1 Vincent Le Goff
71 1 Vincent Le Goff
<pre>
72 1 Vincent Le Goff
#alias go {
73 1 Vincent Le Goff
    #play sounds/go.wav
74 1 Vincent Le Goff
    #say {Here we go!}
75 1 Vincent Le Goff
}
76 1 Vincent Le Goff
</pre>
77 1 Vincent Le Goff
78 1 Vincent Le Goff
For an explanation of the SharpScript syntax, refer to [[SharpScript|the section describing SharpScript]].
79 1 Vincent Le Goff
80 1 Vincent Le Goff
h2. Editing an alias
81 1 Vincent Le Goff
82 1 Vincent Le Goff
At any time, whether you have created the alias in the dialog box or in the configuration file, you can edit it.  If you have created it in the configuration file, you can modify it through the interface, and vice versa.
83 1 Vincent Le Goff
84 1 Vincent Le Goff
Remember that the configuration is loaded when you select the world, which will most likely happen when you open the software.  If you modify the configuration file, restart the software to take it into account.
85 1 Vincent Le Goff
86 1 Vincent Le Goff
h2. Removing an alias
87 1 Vincent Le Goff
88 1 Vincent Le Goff
You can remove an alias through the dialog box or by editing the configuration file.  If you do it through the dialog box, remember the changes will be lost if you close the dialog but do not use the "OK" button.
89 4 Vincent Le Goff
90 4 Vincent Le Goff
h2. Aliases with variables
91 4 Vincent Le Goff
92 4 Vincent Le Goff
CocoMUD provides a system of variables.  They can be used anywhere in your script or in any feature using the SharpScript engine (aliases, macros, triggers...).
93 4 Vincent Le Goff
94 4 Vincent Le Goff
Variables can be more than useful for aliases to create shortcut commands with unknown parameters.  For instance:
95 4 Vincent Le Goff
96 4 Vincent Le Goff
bq. I want to create an alias that begins by @=@.  Everything after the @=@ sign should be sent to the server using the @say@ command.  If I type @=hello !@ in the client, then it should send @say hello !@ to the MUD.
97 4 Vincent Le Goff
98 4 Vincent Le Goff
For this case study, we will use variables.  The alias begins by an equal sign (@=@), but we don't know what's after that.  How to handle that context?  We will use the @*@ sign in our alias name, which means "about everything, as long as necessary".
99 4 Vincent Le Goff
100 4 Vincent Le Goff
So if we enter @=*@ as an alias name, CocoMUD will understand it as meaning "everything starting with an equal sign".
101 4 Vincent Le Goff
102 4 Vincent Le Goff
But we don't only need for the alias to be activated.  We need for it to send a command with what has been entered after the equal sign.  Here is the process step by step, explained below:
103 4 Vincent Le Goff
104 4 Vincent Le Goff
* In the menu bar, select *game* then *aliases*.
105 4 Vincent Le Goff
* Click the *add* button to add a new alias.
106 4 Vincent Le Goff
* In the alias field, enter @=*@ (an equal sign and the asterisk sign).
107 4 Vincent Le Goff
* Tab to move to the list of actions that can be linked to this alias.
108 4 Vincent Le Goff
* Select "send one ore more commands to the server", tab and click the *add action* button.
109 4 Vincent Le Goff
* You'll be asked to configure this action.  Tab until you hear "Commands to be sent to the server".  In this field, type @say $1@ (the @$1@ will be explained below).
110 4 Vincent Le Goff
* Select *OK*.  The action has been linked, and you should see it in this field:
111 4 Vincent Le Goff
<pre>
112 4 Vincent Le Goff
#send {say $1}
113 4 Vincent Le Goff
</pre>
114 4 Vincent Le Goff
What it means will be detailed below.
115 4 Vincent Le Goff
* Tab until you find the *OK* button and click on it.  You will find yourself in the list of aliases, press *OK* again.
116 4 Vincent Le Goff
117 4 Vincent Le Goff
If you type in the client:
118 4 Vincent Le Goff
119 4 Vincent Le Goff
<pre>
120 4 Vincent Le Goff
=hello !
121 4 Vincent Le Goff
</pre>
122 4 Vincent Le Goff
123 4 Vincent Le Goff
The alias will send "say hello !" to the server.
124 4 Vincent Le Goff
125 4 Vincent Le Goff
What happens is pretty simple:
126 4 Vincent Le Goff
127 4 Vincent Le Goff
* You enter "=something".
128 4 Vincent Le Goff
* CocoMUD identifies a matching alias.
129 4 Vincent Le Goff
* The "something" part (after the equal sign) will be captured and put in a variable, called @$1@.
130 4 Vincent Le Goff
* When you send "say $1" to the server, CocoMUD replaces it @$1@ with the "something" part.
131 4 Vincent Le Goff
132 4 Vincent Le Goff
The variable is called @$1@ because you can create a lot of variables.  If you enter the alias:
133 4 Vincent Le Goff
134 4 Vincent Le Goff
<pre>
135 4 Vincent Le Goff
-*+*
136 4 Vincent Le Goff
</pre>
137 4 Vincent Le Goff
138 4 Vincent Le Goff
You will be able to send:
139 4 Vincent Le Goff
140 4 Vincent Le Goff
<pre>
141 4 Vincent Le Goff
remove $1
142 4 Vincent Le Goff
wear $2
143 4 Vincent Le Goff
</pre>
144 4 Vincent Le Goff
145 4 Vincent Le Goff
And then type:
146 4 Vincent Le Goff
147 4 Vincent Le Goff
<pre>
148 4 Vincent Le Goff
-cloak+armor
149 4 Vincent Le Goff
</pre>
150 4 Vincent Le Goff
151 4 Vincent Le Goff
Variables in SharpScript are described more completely in [[SharpScript|the section describing SharpScript]].