This manual covers the more advanced topics of the Astaria Client, such as macros, triggers, aliases, and scripting. Several examples are discussed, including the default set of scripts included with the client.
Macros (keystrokes) are able to be bound from the application's GUI macro interface, as seen below.
This is in essence a wrapper for the macros.txt file included with the client, which can instead be edited manually. The above macro is actually:
macro NUMPAD1
go southwest
/macro
With this macro set, when a user hits the NUMPAD1 key on the keyboard, the action "go southwest" is sent to the MUD.
Aliases are able to be bound from the application's GUI alias interface, as seen below.
This is in essence a wrapper for the aliases.txt file included with the client, which can instead be edited manually. The above alias is actually:
alias quickdrink
get potion from bag of holding
drink potion
/alias
With this alias set, when a string that matches "quickdrink" is sent as input to the MUD, it is translated to the sequence of commands "get potion from bag of holding" and "drink potion" - both of these commands are sent in succession. Aliases are also a great way to make "functions" for more advanced scripting that is discussed later in this manual.
Triggers are scripted responses to text received from Astaria. These are editable from the application's GUI trigger interface, as seen below.
This, just like macros and aliases, is a wrapper for a text file, this time called triggers.txt. The above trigger is actually:
trigger "The combat is over."
bury corpse
get all
put all coins in bag of holding
/trigger
With this trigger, when a string that matches "The combat is over." is sent from the MUD to your screen, the list of specified actions are sent back to the MUD immediately: "bury corpse", "get all", and "put all coins in bag of holding". Triggers can also take wildcard words, specified using {*} in the text of the pattern. The words that match these wildcards are sent to global variables called _trigOutN where N is the position of the wildcard in relation to other wildcards, starting at 0.
The Astaria client provides a scripting language which can be used to perform advanced tasks and calculations. Scripting can be done from the input bar, inside an alias, inside a trigger, or even inside a macro. All script commands start with a / (forward slash). If you want a string to not be considered a command, you can escape it using a // (double forward slash). Below is a list of all available script commands.
Summary: Declares a new variable or alters an existing variable.
Syntax: /set variable, value
Example: /set var0, 25
Result: var0, if it already exists, is set to 25. If var0 does
not exist, it is declared with a value of 25.
Notes: Variables are maintained across sessions, and get saved
to your variables.txt file. In order to retrieve the
value of the variable, encase the variable's identifier
with {} (curly-braces). Wherever a command (like /echo)
takes a value, {yourvariable} can be inserted to retrieve
the variable's value.
Summary: Deletes an existing variable.
Syntax: /delete variable
Example: /delete var0
Result: var0, if it exists, is deleted. If var0 does not exist,
an error is printed.
Summary: Prints a summary of every current variable.
Syntax: /variables
Example: /variables
Result: A list of every variable is printed to the output screen,
along with each variable's associated value.
Summary: Echoes a command locally to the client output screen.
Syntax: /echo message, [optional color code]
Example: /echo Hello there!, 0FB0A0
Result: Hello there! is sent to the client output screen.
Notes: You can put values of variables in a message sent to /echo
by using the curly brace notation. For example, your message
could be: the current count is {currentCount}. This will
replace {currentCount} with the value of currentCount. If no
hexidecimal color code is specified, the client uses FFFFFF,
which is bold white.
Summary: Adds a value to a variable.
Syntax: /add variable, value
Example: /add var0, 25
Result: The value of var0 is set to {var0} + 25.
Notes: This command operates on strings by concatenating the value
parameter onto the end of the specified variable.
Summary: Subtracts a value from a variable.
Syntax: /subtract variable, value
Example: /subtract var0, 25
Result: The value of var0 is set to {var0} - 25.
Notes: This command bails out and performs no operation when given
strings.
Summary: Multiplies a variable by a value.
Syntax: /multiply variable, value
Example: /multiply var0, 25
Result: The value of var0 is set to {var0} * 25.
Notes: This command bails out and performs no operation when given
strings.
Summary: Divides a variable by a value.
Syntax: /divide variable, value
Example: /divide var0, 25
Result: The value of var0 is set to {var0} / 25.
Notes: This command bails out and performs no operation when given
strings.
Summary: Compares if value0 is equal to value1.
Syntax: /isequal value0, value1
Example: /isequal {var0}, 25
Result: Checks if the value of var0 is equal to 25. If so, the next
call to /cond or /condloop will pass.
Summary: Compares if value0 is not equal to value1.
Syntax: /isnotequal value0, value1
Example: /isnotequal {var0}, 25
Result: Checks if the value of var0 is not equal to 25. If so, the
next call to /cond or /condloop will pass.
Summary: Compares if value0 is less than value1.
Syntax: /islessthan value0, value1
Example: /islessthan {var0}, 25
Result: Checks if the value of var0 is less than 25. If so, the
next call to /cond or /condloop will pass.
Notes: This command's behavior is undefined for strings.
Summary: Compares if value0 is greater than value1.
Syntax: /isgreaterthan value0, value1
Example: /isgreaterthan {var0}, 25
Result: Checks if the value of var0 is greater than 25. If so, the
next call to /cond or /condloop will pass.
Notes: This command's behavior is undefined for strings.
Summary: Compares if value0 is less than or equal to value1.
Syntax: /islessthanorequal value0, value1
Example: /islessthanorequal {var0}, 25
Result: Checks if the value of var0 is less than or equal to 25. If
so, the next call to /cond or /condloop will pass.
Notes: This command's behavior is undefined for strings.
Summary: Compares if value0 is greater than or equal to value1.
Syntax: /isgreaterthanorequal value0, value1
Example: /isgreaterthanorequal {var0}, 25
Result: Checks if the value of var0 is greater than or equal to 25.
If so, the next call to /cond or /condloop will pass.
Notes: This command's behavior is undefined for strings.
Summary: Conditionally executes the specified command.
Syntax: /cond command
Example: /cond go east
Result: If the last call to /isequal, /isnotequal, /islessthan,
/isgreaterthan, /islessthanorequal, or /isgreaterthanorequal
passed, "go east" is sent to the MUD.
Notes: The command executed can be another script command, or even
an alias.
Summary: Conditionally executes the specified command as long as the
condition holds.
Syntax: /condloop command
Example: /condloop loop_body
Result: If the last call to /isequal, /isnotequal, /islessthan,
/isgreaterthan, /islessthanorequal, or /isgreaterthanorequal
passed, the alias entitled loop_body is executed as long as
the condition holds true.
Notes: The best way to use a /condloop is to write an alias that is
in charge of performing the looped actions and alters the
condition. See the next section for some advanced examples.
Summary: Executes the given command the specified number of times. An
alias or another script command can be used for the command.
Otherwise, the command is sent to Astaria the specified number
of times. A variable's value can be used as the number of
iterations by using curly braces i.e. {var0}
Syntax: /repeat number, command
Example: /repeat 12, go west
Result: The command string "go west" is sent to the MUD twelve times.
Summary: Pauses execution of the current series of commands, resuming
after the specified time.
Syntax: /pause timerid, milliseconds
Example: kill monster;/pause killtimer, 1500;look at monster
Result: The command "kill monster" is sent to the Astaria. After one
and a half seconds, the command "look at monster" is sent to
Astaria.
Notes: Notes: You must have a string specified in the application's
settings as an "input split" to take advantage of this feature.
Also, timerid must be unique for each /pause currently
pending.
Summary: Removes a pending timer, stopping its queued actions from
executing.
Syntax: /unpause timerid
Example: /unpause killtimer
Result: The timer called "killtimer" is removed from memory and its
queued actions do not occur.
What follow are some advanced examples using clientside scripting.
Keeping track of the last monster you killed involves two things - a trigger using wildcards and a variable. For convenience, this example also provides an alias for displaying the name of that monster at the user's whim.
trigger "{*} dies in fits of twitching agony."
/set LastMonsterKilled, {_trigOut0}
/echo You just killed: {LastMonsterKilled}
/trigger
The trigger performs two tasks. First, it sets a variable called LastMonsterKilled to the string that matched the wildcard word, which was specified in the trigger pattern using a {*}. Next, it echoes that variable back to the user using /echo's default white color.
alias lastkill
/echo Your last kill was: {LastMonsterKilled}
/alias
The alias simply outputs the value of the LastMonsterKilled, which was set in the previous trigger. By entering the command "lastkill", the user can retrieve the name of the last monster he or she killed.
Calculating experience gained from combat is a bit trickier than merely keeping track of the last monster you have slain. This example involves several parts - a trigger for when combat is over, a trigger for intercepting your current amount of experience, and an alias for calculating the experience gained since your triggers last went off.
trigger "The combat is over."
/set CombatJustEnded, 1
xp
/trigger
This trigger makes sure that combat ends, you issue an "xp" command to the MUD to check your current experience. It also sets a variable called CombatJustEnded which is used when calculating experience.
trigger "Your current experience points: {*}"
/isequal {CombatJustEnded}, 1
/cond calculate_exp_gained
/trigger
This trigger conditionally calls the alias for calculating experience gained from combat. If we just left combat, then we should calculate the experience gained. If a user is just checking his or her experience points at another time, we skip calculation.
alias calculate_exp_gained
/set CurXP, {_trigOut0}
/set DiffXP, {CurXP}
/subtract DiffXP, {OldXP}
/set OldXP, {CurXP}
/echo Experience gained from combat: {DiffXP}, 00FFFF
/set CombatJustEnded, 0
/delete CurXP
/delete DiffXP
/alias
This alias calculates the amount of experience gained since the alias was last called. Note the use of the _trigOut0 variable to access the wildcard value from the previous trigger. The experience gained is echoed back to the local user in a cyan color. Also note that before the alias terminates, the combat tracking variable is reverted to a state that signifies "combat didn't just end." Finally, the variables that aren't necessary to maintain across multiple calls are deleted
This example shows how to generate a text-based health bar whenever the user checks his or her current health.
trigger "hp: [ {*} / {*} ], sp: [ {*} / {*} ], ep: [ {*} / {*} ]"
/set CurHP, {_trigOut0}
/set MaxHP, {_trigOut1}
/set PercentHP, {CurHP}
/divide PercentHP, {MaxHP}
/set NumIterations, {PercentHP}
/multiply NumIterations, 49
/set BarOutput, Health: [#
/repeat {NumIterations}, /add BarOutput, #
/set RemainderIterations, 49
/subtract RemainderIterations, {NumIterations}
/repeat {RemainderIterations}, /add BarOutput, .
/add BarOutput, ]
/echo {BarOutput}, 00FFFF
/delete CurHP
/delete MaxHP
/delete PercentHP
/delete NumIterations
/delete RemainderIterations
/delete BarOutput
/trigger
This trigger grabs the current health and maximum health of the user whenever he or she issues the "hp" command to the MUD. It then calculates the percentage of health the user has, and then generates a bar using /repeat calls and /add. All used variables are deleted when the trigger is done executing.
A task that players often want to perform clientside is tracking when an ability he or she has used is ready to be used again. In this example, we do so for a fighter's berserk ability. This is actually relatively simple and involves one trigger.
trigger "Your eyes blaze with immeasurable rage as an irrational, savage hatred"
/pause BerserkTimer, 60000
/echo You can now use berserk again.
/trigger
The first step in creating this trigger was figuring out the first line when berserk is cast. Once this line is discovered, we created a trigger using that line as the pattern, and inside the trigger we use a call to /pause, creating a timer. The number of milliseconds that /pause must wait is determined by experimenting in-game and figuring out the power's cooldown. In this case, berserk takes one minute (or 60,000 milliseconds) to cool down.