EQWatcher Evolution Tutorials > Scripting  > Introduction


Caution: A new EQWatcher Script Compiler is being built, which will slightly change the language (although most will remain the same).  When that is ready and released, I will be re-doing this documentation.

EQWatcher Evolution is a program that simply does what scripts instruct it to do.  Most of its functionality comes from a script that I wrote for your use, using the EQWatcher Evolution scripting language.  This language was built with simplicity in mind, and uses a format that looks familiar to veterans of mainstream programming.

Scripts are just a series of instructions that tell EQWatcher what to do when something happens.  When you want it to squeak, it'll squeak.  When you want it to bark, it'll bark.  When you say jump, EQWatcher says how high (not literally, and EQWatcher won't jump for you).  When you want it to calculate your damage per second, you figure out what math it has to do and it'll damn well do it.  When you want it to wait half a second and tell you you're an idiot, it'll tell you you're an idiot.

EQWatcher uses "compiled" scripts.  This means that most errors are caught before the instructions are actually used by EQWatcher.  A script compiler converts the "source code" into a series of numbers -- these numbers make perfect sense to EQWatcher, but would look like a jumbled mess to a human.  When the compiler detects a problem in your script's source code, it will not allow the conversion to complete and the script won't be able to be used.  The fact that a compiler is used also allows for completely different languages or compilers to be created that produce the same (or even better) series of numbers for EQWatcher to use -- all of the information found in the EQWatcher Evolution documentation and tutorial applies only to the compiler provided. 

EQWatcher's scripting language is event-driven.  Basically it will do something after a specified amount of time, when it sees something in the EQ log file, or when it sees something in the EQ notes file.  The easiest to understand is probably to have it do something when something shows up in your chat window (such as bark when you get a tell).

Scripts are divided into sections of instructions meant to be executed on particular events.  These sections are called "functions".  If you have taken math classes, you may be familiar with functions.  In general, functions take some piece of information, do something with it, and spit something back out.  You may have seen something like f(x)=2x in math class.  That function takes a number, multiplies it by two, and spits back out the result.  The idea of functions in programming is much like that.

EQWatcher Evolution scripting has three types of functions: basic functions, triggers, and aliases.  Each basic function may have up to 7 parameters (in the math example above, the variable x was the parameter to the function).  Triggers and aliases allow only one parameter, which is the text that triggers the event.

Basic functions are defined like this:

function MyFunction()

The word "function" tells the EQWatcher Evolution Script Compiler that it should look for a function.  "MyFunction" is the name of the function, used to tell other parts of the script to use the instructions in this section.  The parentheses () would contain information about parameters, but in this case remain empty to signify no parameters allowed.

Immediately following the "function" line, you must signify a block of code -- starting with a "{" and ending with a "}", each should be on their own line.  Blocks of code are required for functions, and may be used anywhere within functions as well to separate subsections of code.

The basic function definition now looks like this:

function MyFunction()
{
}

Instructions are then placed within the block.

Every script is required by EQWatcher to have a function called "main" as the FIRST function, and this function is required to have no parameters.  The instructions in the main function are executed as soon as the compiled script is loaded by EQWatcher.  There can only be ONE main function per script -- there can only be one function with any given name per script as a matter of fact.  This might sound obvious at this point, but it is potentially easy to miss when dividing large scripts into different files and having the compiler combine them later.

Aliases and Triggers are defined in much the same way, except they are required to have one parameter, and that one parameter must be the text to look for.  Any string of characters (text) in this language must be encompassed by quotation marks, i.e. "This is a string".  Some strings need to have quotation marks within them, but quotation marks signify the beginning or end of a string... to solve this problem, a special character is used to tell the compiler to use it within the string -- and that is the backslash \. Therefore, "Mom says \"hello\"" becomes "Mom says "Hello"" when it is finally used.  Please keep in mind that this only applies to the scripting language and compiler, not to EQWatcher itself. 

 Here is an example of an alias and a trigger:

alias("test alias")
{
}

trigger("[@trash@] orc centurion is straight ahead.")
{
}

Part of the text used for the trigger may look cryptic now, but you will soon learn about it.

Now you should have an idea of how to create functions and outline sections of code, so on to instructions.  Functions do exactly nothing if they are not instructed to do anything at all -- this should make perfect sense.  Unfortunately, it's a big waste to do nothing at all and really nobody wants to make something that does nothing at all.  Well, it's time to tell the function exactly what to do.

Instructions generally consist of the name of a function and data to process -- hopefully this sounds familiar from a few paragraphs up.  To instruct EQWatcher to run the function you named "MyFunction", you would simply use the name of the function, followed by the parentheses (since it allows no parameters):  "MyFunction()".  Each instruction is separated by at least a semi-colon ;, and usually the end of the line.  Instructions may be placed on the same line, but it is generally good practice to place each on its own line for the sake of readability.

The example alias could now be:

alias("test alias")
{
  MyFunction();
}

I have slightly indented the instruction, using two spaces.  This is done for readability and to help distinguish between sections of code.

This alias is executed when you type "test alias" as an EQWatcher command (for example, typing "/note test alias" within EQ).  The function (remember, every alias and trigger is a function) then executes the other function MyFunction.  Functions can execute any number of instructions.

There is a large number of built-in functions to instruct EQWatcher to run, all of them defined in the Scripting section of the documentation.

By now you should realize the need for (or at least this should have crossed your mind) some way of storing and retrieving values that are not already known.  What if you wanted to find out the current time and use that as part of some function, or the current character's name?  Variables do exactly this.  A variable is basically just a part of your computer's memory reserved for some use like grabbing a character's name and manipulating that in some fashion.  EQWatcher's variables are all used in specific ways -- numbers are stored as numbers, and strings of characters are stored as strings of characters.  EQWatcher does not support user-defined data types, and the types allowed are clearly listed in the variables section of the documentation under scripting.

Variables are declared by specifying the type of variable, and the name.  Variables in EQWatcher are automatically set to a specific value (0, false, or "", depending on the type), so there is no need to initialize them to this value (this information is mostly for veteran programmers).