Xelagot action script

Events

What must you do if you want the bot to react to unpredictable things, like chat, avatars entering, moving, clicking, departing, or disconnection? For predictable things, you use Goto and Gosub to re-direct the flow of the script. For unpredictable things you use event handlers: the bot itself decides when to jump to an event handler, you do not use Gosubs for that.

The bot is event-driven. Events happening in AW (chat, detection of movement etc) are trapped by the main program and can also be trapped by scripts. To do so, you must define and install an event handler:

An event handler is defined after the End statement of the script, in the same region you define the Subs (it is, in fact, a special kind of sub). The syntax is:

Event <eventlabel>
#your code here
EndEvent

You can define various event handlers for the same event. These can be used a different moments in the script, but only one can be used at any time. To use an event handler you defined, you need to install it at an appropriate place in the script. This can be anywhere, in the main part, in a Sub or in an event handler.

To install the event handler, you will need to specify the sort of event you are trapping and the event handler, using an installer. For example, for the chat event you would write:

OnChatEvent <eventlabel>

To uninstall an event handler, omit the eventlabel.

OnChatEvent

You can switch handlers for an event, just re-install it to another eventlabel.

Each event has a type, defined in GetEventType %e. See each event section for this code. Each event has also a GetEventResult %r code, identical in most cases to the SDK rc code: 0 indicates success. In some event types this code will always be 0.

Example:

[Head]
Type=Script
Version=2.0

[Settings]
Origin=0.000n 0.000w 0.00a 0.0°

[Script]
   WhisperControl 1
   OnChatEvent BotChat
   Label Start
   Goto Start
End

Event BotChat
   GetChatLine $a
   GetChatName $n
   Concat $b "I heard " $n " say: " $a   
   Say $b
   ChatImpair 3
EndEvent

In event handlers you must follow certain rules, due to the fact that they interrupt the execution of the script without changing its flow. In an event handler:

you must not attempt to alter the flow of the main script directly using a Goto. After the Event handler exits, the script continues where it was when interrupted by the event. You can use Goto to go to a label in the same event handler, or in the same Sub. If you use a Goto to a label outside its own sub, or if no sub is called, outside the event handler, the script will abort. See Errors and debugging.
if necessary, you can alter the flow of the main script from within the event handler using ResetTo label, which resets the script pointer to a label in the main script, clears the Sub stack, and disables any Wait command after the event handler exits. The ResetTo statement will start being effective when the main script resumes execution. It will not exit a Sub called by an event handler, as it would if the Sub had been called from the main part of the script, nor will it exit the event handler. As from x1.exe version 2.9999950 (other bots 1.66), you can also use EscapeTo label, which has the same effect as ResetTo but exits the handler inmediately (even from within a Sub called by the event handler). The label pointed to in the ResetTo or EscapeTo statement must be in the main script (not in a sub or event handler), or the script will abort with an error message. See Errors and debugging..
if you wish to exit an event handler before EndEvent is reached, you have two choices:
1. if you are in the body of the event handler (not in a Sub called by it), you can use EndEvent, on its own line or in a conditional statement, for example:
  IfInt %r = 1 EndEvent
  The last EndEvent (on its own line) before a new Sub, Event or Text is the one that closes the Event handler.
2. (x1.exe version 2.9999950, other bots version 1.66) if you are in a Sub or even in the body of the event handler, you can exit by using Escape (Escape can be used also in Subs called from the main section as from this version).
you must gather the pertinent information as soon as possible. Information given in an event handler (persons, chatlines, target...) is shielded within the event handler (no other events can be triggered while you are there, it is protected and safe code), but will change once you exit the event handler and, even before the main script is resumed, other events may be triggered, which can write over the values of your variables. If, for example, you need to remember the person who said something so as to take some action in the main script, once you have done GetChatPerson &p in the even handler, keep &p in another variable, which you shall only use for this case: &z = &p (and if necessary, disable Chat events until you are finished).
you must be as brief as possible: event handlers freeze the whole application, usually for milliseconds at a time, and no other code can be executed by the application while you are in there (well, except for other threads, but these must synchronise with the main thread where your script is running). An example of how to handle if you need to do lengthy operations as a result of an event can be seen in Errors and debugging.
you must not remain in a loop, loops if used at all must be short lived. Long loops in an event handler or in a Sub called by the event handler can freeze or crash the program. The bot protects itself in those cases by aborting the script. See Errors and debugging.
when calling Subs from within an event handler, you should bare in mind that all variables are shared. You might want to make special subs for event handlers.

Index