Project

Profile

Help

SharpScript » History » Sprint/Milestone 2

Vincent Le Goff, 09/29/2016 03:36 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
{{toc}}
6
7
h2. The SharpScript logic
8
9
The logic of the SharpScript can be summarized in two main ideas:
10
11
* Have a very easy-to-write language to perform simple functions ;
12
* Allow to include Python code in this language to perform more complex tasks.
13
14
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.
15
16
h2. Basic syntax
17
18
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.
19
20
h2. Commands
21
22
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.
23
24
Here's a single example:
25
26
<pre>
27
#say Hello!
28
</pre>
29
30
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.
31
32
The @#say@ command that we have used is very simple:  It expects one argument, one information, which is the message to be displayed.
33
34
h2. Arguments with spaces
35
36
If you try to display a message with spaces, it will not work:
37
38
<pre>
39
#say This character isn't feeling so well.
40
</pre>
41
42
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 ({}) :
43
44
<pre>
45
#say {This character isn't feeling so well.}
46
</pre>
47
48
Surrounding arguments by braces is only necessary if this argument contains spaces.  Consider the following example, to create a [[Macro|macro]]:
49
50
<pre>
51
#macro F1 north
52
</pre>
53
54
This time, the @#macro@ command expects two arguments:
55
56
* The shortcut to which this macro should react.
57
* The action to be performed.
58
59
Here, when we press F1, the client will send "north" to the server.
60
61
Remember to enclose the arguments containing spaces, however:
62
63
<pre>
64
#macro {Ctrl + F1} north
65
</pre>
66
67
This time, the shortcut is Ctrl + F1. Because there are spaces in this argument, we enclose it in braces.
68
69
<pre>
70
#macro F8 {say Greetings!}
71
</pre>
72
73
When we press F8, the client will send "say greetings!" to the server.
74
75
<pre>
76
#macro {Ctrl + Shift + K} {look into backpack}
77
</pre>
78
79
Since both arguments contain spaces, we enclose them both.
80
81
Notice that if you have a doubt, use braces.  It will work regardless:
82
83
<pre>
84
#macro {F1} {north}
85
</pre>
86
87
h2. Multi-line scripts
88
89
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.
90
91
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:
92
93
<pre>
94
#alias victory {
95
    #play victory.wav
96
    say I've done it!
97
    north
98
    #wait 3
99
    sheathe sword
100
}
101
</pre>
102
103
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.
104
105
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.
106
107
h2. Flags
108
109
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:
110
111
* "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.
112
* "speech":  Should the text be sent to the screen reader to be spoken aloud?  Once again, if not changed, it's on.
113
* "braille":  Should the text be sent to the Braille display?  Again, this flag is on by default.
114
115
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 (-).
116
117
<pre>
118
#say {I don't want it to be displayed.} -screen
119
#say {And that shouldn't be spoken nor displayed in Braille.} -speech -braille
120
#say {This may be displayed on screen and on the Braille display.} +screen -speech +braille
121
</pre>
122
123
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.
124
125
h2. Embedding Python into SharpScript
126
127
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.
128
129
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.
130
131
If we want to write a script that plays different sounds depending on the XP we receive, we might do it that way:
132
133
<pre>
134
#trigger {You received {xp} XP.} {+
135
    # The 'xp' variable contains the received XP
136
    # It might be a number, but we have to convert it
137
    if xp.isdigit():
138
        if xp > 200:
139
            play("victory.wav")
140
        elif xp > 100:
141
            play("notbad.wav")
142
        elif xp > 10:
143
            play("notalot.wav")
144
}
145
</pre>
146
147
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:
148
149
* If the received XP is over 200, it will play "victory.wav".
150
* If it's between 100 and 200, it will play "notbad.wav".
151
* If it's between 10 and 100, it will play "notalot.wav".
152
153
Notice that nothing happens if you receive less than 10 XP in this example.
154
155
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.
156
157
h2. Frequent questions
158
159 2 Vincent Le Goff
Here is a list of frequently asked questions:  You can click on a question, the answer will appear on the next line.  Click again on the question if you want to hide the answer.
160
161
{{collapse(Which functions are available in embedded Python?)
162
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:
163
164
<pre>
165
say("Could you display that?")
166
say("After all, just speak that.", screen=False)
167
play("sound/file.ogg")
168
</pre>
169
}}
170
{{collapse(What variables are available in embedded Python?)
171
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:
172
173
<pre>
174
#alias todo {+
175
    health = 38
176
}
177
</pre>
178
179
The variable 'health' will be available in all other Python scripts.
180
181
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]].
182 1 Vincent Le Goff
}}