Project

Profile

Help

SharpScript » History » Sprint/Milestone 3

Vincent Le Goff, 09/29/2016 07:30 AM

1 1 Vincent Le Goff
h1. Scripting in project:cocomud-client
2
3
project:cocomud-client offers a simple yet easily-extendable scripting language.  This language can be used to describe macros, aliases or triggers, or more complex features in the MUD.
4
5 3 Vincent Le Goff
This document describes the syntax of SharpScript, gives examples and provides frequent questions at the bottom of each section.  If you want the answer to one of these questions, just click on the question, the answer will appear on the next line.
6
7 1 Vincent Le Goff
{{toc}}
8
9
h2. The SharpScript logic
10
11
The logic of the SharpScript can be summarized in two main ideas:
12
13
* Have a very easy-to-write language to perform simple functions ;
14
* Allow to include Python code in this language to perform more complex tasks.
15
16
As you will see, the syntax of the SharpScript is pretty light, but it already allows interesting features.  Should you need more, Python is here, and it's not exactly a limited alternative.
17
18
h2. Basic syntax
19
20
The SharpScript finds its name in its syntax.  As most MUD clients, a SharpScript command begins with a sharp symbol (@#@).  It can already feel like a constraint of some type, but maintaining the difference between commands to the server and to the clients is important.  Unlike most MUD clients, project:cocomud-client tries to not force symbol in user input.  If you want to send a message beginning with the sharp symbol, you can do so, unless you configure your client to interpret SharpScript as input.
21
22
h2. Commands
23
24
SharpScript features are kept in commands (or functions).  Both terms refer to the same thing in this documentation.  These commands can ask to create a [[Macro|macro]], an [[Alias|alias]], a [[Trigger|trigger]], send some message to the server, display some message to the client, prompt the client with a question, store some information about a character and so on.
25
26
Here's a single example:
27
28
<pre>
29
#say Hello!
30
</pre>
31
32
If you try this piece of SharpScript in an input that accepts SharpScript syntax, the client should display "Hello!" at the bottom of your screen.  The text should also be sent to the screen reader, spoken by it and displayed on a Braille display, if supported.
33
34
The @#say@ command that we have used is very simple:  It expects one argument, one information, which is the message to be displayed.
35
36 3 Vincent Le Goff
Frequent questions:
37
38
{{collapse(How to send a command with a sharp symbol (#) in it?)
39
By default, project:cocomud-client doesn't interfere with your playing.  When you are in the input field on the client, you cannot enter SharpScript unless you enable that setting.  So you can type about every symbol you want, none of them will be interpreted by the client.
40
41
However, at times, you really want to send sharp signs to the client while having SharpScript interpret part of your commands.  To do so, you must precede the sharp sign (#) with another one.  This syntax is only necessary at the beginning of a command or an argument:
42
43
<pre>
44
#say {{##I'm saying something with a #.}
45
</pre>
46
47
This will display: @#I'm saying something with a #.@
48
49
Notice that only the first sharp symbol had to be kept twice (at the beginning of the argument).  The other (at the end) didn't need to be escaped.
50
51
<pre>
52
##forward
53
</pre>
54
55
This will send @#forward@ to the client.
56
}}
57
58 1 Vincent Le Goff
h2. Arguments with spaces
59
60
If you try to display a message with spaces, it will not work:
61
62
<pre>
63
#say This character isn't feeling so well.
64
</pre>
65
66
Some commands take more than one argument, and to separate them, they use the space (we will see examples a little below).  Therefore, if you want to have spaces in your argument, you should surround it by braces ({}) :
67
68
<pre>
69
#say {This character isn't feeling so well.}
70
</pre>
71
72
Surrounding arguments by braces is only necessary if this argument contains spaces.  Consider the following example, to create a [[Macro|macro]]:
73
74
<pre>
75
#macro F1 north
76
</pre>
77
78
This time, the @#macro@ command expects two arguments:
79
80
* The shortcut to which this macro should react.
81
* The action to be performed.
82
83
Here, when we press F1, the client will send "north" to the server.
84
85
Remember to enclose the arguments containing spaces, however:
86
87
<pre>
88
#macro {Ctrl + F1} north
89
</pre>
90
91
This time, the shortcut is Ctrl + F1. Because there are spaces in this argument, we enclose it in braces.
92
93
<pre>
94
#macro F8 {say Greetings!}
95
</pre>
96
97
When we press F8, the client will send "say greetings!" to the server.
98
99
<pre>
100
#macro {Ctrl + Shift + K} {look into backpack}
101
</pre>
102
103
Since both arguments contain spaces, we enclose them both.
104
105
Notice that if you have a doubt, use braces.  It will work regardless:
106
107
<pre>
108
#macro {F1} {north}
109
</pre>
110
111
h2. Multi-line scripts
112
113
By default, SharpScript expects every command to be on a different line.  This is not always a good thing for readability's sake, and sometimes it can get really complicated.
114
115
Let's say we want to create the [[Alias|alias]] as follows:  When we enter "victory", the client plays a sound and sends a few commands to the server:
116
117
<pre>
118
#alias victory {
119
    #play victory.wav
120
    say I've done it!
121
    north
122
    #wait 3
123
    sheathe sword
124
}
125
</pre>
126
127
The second argument is split on several lines, because it's much more readable.  Notice here that the argument contains SharpScript commands (beginning with a sharp symbol) and commands to be sent to the server.  The lines not beginning with a sharp symbol (#) are sent as it to the server.  This is the case for the line 3 (say I've done it!) for instance.
128
129
For readability, the second argument is indented a little on the right:  Each command in this second argument stands 4 space on the right.  This is not mandatory, it just makes things easier to understand.  Since Python relies on indentation however, it might be a good thing to get used to it, regardless of its being necessary or not.
130
131 3 Vincent Le Goff
Frequent questions:
132
133
{{collapse(Can I put several instructions on a single line?)
134
You can, although it might not be very readable.  The syntax to do so is to use semi-colons to separate commands on a single line.  The previous example could be written on a single line like this:<pre>
135
136
<pre>
137
#alias victory {#play victory.wav;say I've done it!;north;#wait 3;sheathe sword}
138
</pre>
139
140
As you can see, it's not as readable, but this syntax may sometimes be useful.
141
142
If you want o write a semi-colon in your SharpScript command, just put two semi-colons instead of one:
143
144
<pre>
145
#say {I would like to display something;; but I'm not sure what.}
146
</pre>
147
}}
148
149 1 Vincent Le Goff
h2. Flags
150
151
Some commands support flags:  Flags are here to influence the behavior of a function in some way.  The best example available at this time is the @#say@ command we have seen.  By default, it displays the provided text, sends it to the screen reader to be spoken, and to the Braille display to be displayed.  There are three flags that control that:
152
153
* "screen":  Should the text be displayed on the screen (as if it were coming from the server)?  If you don't change it, it's on by default.
154
* "speech":  Should the text be sent to the screen reader to be spoken aloud?  Once again, if not changed, it's on.
155
* "braille":  Should the text be sent to the Braille display?  Again, this flag is on by default.
156
157
You can change flags given to a command at the end of the SharpScript line (or instruction).  To set a flag on, write its name after a plus sign (+).  If you want to set this flag off, write its name after a minus sign (-).
158
159
<pre>
160
#say {I don't want it to be displayed.} -screen
161
#say {And that shouldn't be spoken nor displayed in Braille.} -speech -braille
162
#say {This may be displayed on screen and on the Braille display.} +screen -speech +braille
163
</pre>
164
165
Notice that the flags "screen" and "braille" are not necessary in the last example:  Both are on by default.  This example is here to illustrate the syntax.
166
167
h2. Embedding Python into SharpScript
168
169
Sometimes, what we want to do is a bit too complex in SharpScript.  It's possible to extend its syntax and bring new commands into it, but it's better to keep it simple and to learn to do more complex things with Python, which is a highly-readable language without few limitations.  It's still a good thing to keep your script readable, not only for you (although it might be handy, should you modify it), but to potential users.
170
171
To add Python code, use the syntax for long arguments (with braces), but after the left brace, add a plus sign (+).  This tells the client that what follows between the braces isn't SharpScript, but Python code.
172
173
If we want to write a script that plays different sounds depending on the XP we receive, we might do it that way:
174
175
<pre>
176
#trigger {You received {xp} XP.} {+
177
    # The 'xp' variable contains the received XP
178
    # It might be a number, but we have to convert it
179
    if xp.isdigit():
180
        if xp > 200:
181
            play("victory.wav")
182
        elif xp > 100:
183
            play("notbad.wav")
184
        elif xp > 10:
185
            play("notalot.wav")
186
}
187
</pre>
188
189
This trigger will wait for the line @"You received *** XP."@ and will put whatever XP in the 'xp' variable, before passing it to the Python script.  The Python script will convert the XP (if it's a number) and will play a different sound:
190
191
* If the received XP is over 200, it will play "victory.wav".
192
* If it's between 100 and 200, it will play "notbad.wav".
193
* If it's between 10 and 100, it will play "notalot.wav".
194
195
Notice that nothing happens if you receive less than 10 XP in this example.
196
197
It's very useful to embed Python code into SharpScript that way.  It makes for clear and readable scripts that are almost limitless.  Keep the indentation in this example, as it will be used by Python to determine blocks.
198
199 3 Vincent Le Goff
Frequent questions:
200 2 Vincent Le Goff
201
{{collapse(Which functions are available in embedded Python?)
202
All SharpScript commands are available as functions.  That's why you can use the @#play@ or @#say@ command.  Inside of Python, the commands are not preceded by a sharp sign and are just respect the function syntax:
203
204
<pre>
205
say("Could you display that?")
206
say("After all, just speak that.", screen=False)
207
play("sound/file.ogg")
208
</pre>
209
}}
210
{{collapse(What variables are available in embedded Python?)
211
Python scripts share their variable across the entire game setting.  This can sometimes be confusing, but it also prevents from bad headaches if you remember that no variable defined in a script will magically disappear unless you close the program.  Therefore, if you have a script like this:
212
213
<pre>
214
#alias todo {+
215
    health = 38
216
}
217
</pre>
218
219
The variable 'health' will be available in all other Python scripts.
220
221
In some cases, other variables are defined by the client.  For instance, the @#trigger@ command creates variables depending on the trigger.  For more information, read [[Trigger|the section about triggers]].
222 1 Vincent Le Goff
}}