AGAST - Events

Script Language: Declarations: Events

These are all the events that the interpreter will generate. The script programmer may define these events to describe what happens in the game when the event actually is triggered.

When most events are triggered, user input is suspended, and the programmer gets control of the game. (Exceptions are noted.) It is the programmer's responsibility to give control back to the user with the resume function.

In the events that can be declared in both scene and game scope, the scene scope event will override the mathcing game event only if present, and may be defined differenty in each scene. Scenes without that event in scene scope will automatically use the event at game scope.

For a practical example, imagine you have a lighter. Usually, using the lighter will light a little light, and say "My what a pretty light." But if the player finds himself in a dark room, it may light up the room. And if the room is full of dynamite, it might really light up!

Main

event main { }

Main is triggered only once, when a new game is started, to set the game in motion. Here is an example that initializes the interpreter and loads the first scene.

As you can see, main has lots of responsibilities. For a more detailed example, look at sample game or script files included with the most recent AGAST distribution.

event main
{
     // set default font
   defaultFont = MyFavorite_font;

     // Choose which object the player controls
     playerObject = Ego;

     // enter the game's first scene
   enter FrontOfCastle;
}

The first scene need not be a place; it can instead be an introduction sequence or title screen that, in turn, loads the first playable scene.

(BTW, this isn't an obscure reference to the so-called sport of wresting, but a parallel to the C-language's function main.)

Enter

event enter { }

Enter is triggered every time the player enters a scene called SceneName. This event is used to initialize the scene.

event enter
{
   background = Cave_image; // set the background image
     zbuffer = Cave_zbuffer;   // ...and the zbuffer

     // call functions to start animation effects
     start TorchFlickering;
     start DrippingWater;

     // initialize variables that are used in this scene,
     // or whatever else...

     resume; // give control back to the user
}

There's no exit-event because it isn't necessary: if desired, the programmer can call an exit script or perform any kind of clean-up before entering a new scene with the enter-statement.

Click

event click { }

This event will be triggered whenever the user clicks any place on the screen that isn't already covered by some clickable object's click area. Just think of it as the "miss" event!

In most situtions, the object should walk to the point the user clicks (or the nearest possible point in the current path).

event click
{
resume; // give control back to the user
walk(clickX, clickY);
}

The exact point the user clicked to trigger the event is a property of that event, and it can be read with the functions clickX and clickY.

Object-on-Object

event SourceObject -> TargetObject { }

An object-on-object event is triggered when an object is "used" on another object. Most of the time, you'll use this to represent the use of an inventory object on something in the environment. The example inventory interface included with the example games triggers object-on-object events when the user clicks the selected object on an object in the environment.

So if the object is a coffee vending machine, and the player puts in a quarter, the vending machine might dispense a cup of hot coffee.

event EmptyMug -> VendingMachine
{
   Ego:
     dropItem(Quarter);
     print("You insert a quarter, and the machine fills your mug.");
     giveItem(MugOfCoffee);
     resume; // give control back to the user
}

event default -> TargetObject { }

A default-on-object event is triggered when an any object is "used" on another object, and the interaction is not explicitly handled by an object-on-object event.

Click-Object

event click AnObject { }

A click-object event is mainly used to respond to the user right-clicking an object. By defining this event, you define what happens when the user right-clicks an object. If the object is a door, this can be used to open or close it, or if it's a person, you might want the click-object event to cause the player to talk to him.

Default-on-Default

event default -> default { }

The default-on-default event is triggered when the player uses two objects, which have no specific event or specific default event handler. This is the event that might generate the infamous "What are you trying to do?" response when the player does something unexpected.

This example causes the player's object to say a random message.

event default -> default
{
   switch random(4) {
     case 0: "I can't do that."
     case 1: "What are you trying to do?"
     case 2: "Let's not, and say we did."
     case 3: "I can assure you, that won't be necessary."
     }
     resume; // give control back to the user
}

Object-on-Default

event objectName -> default { }

This event is triggered whenever the user clicks an object without an object-on-object event defined for it. When applicable, it superceeds all the other inventory-related default events.

Key Event

event <KeyCode> { }

Key-events are triggered by the input handler whenever the matching key is pressed. Of course, this behavior can be modified in any way by modifying the input handlers.

Notes:

The key-event does NOT suspend user input by default.
Watch out, because the compiler will not notice duplicate key-events in the same scope, and only one will be called. But like all events allowed in both game and scene levels, a scene level event will override the matching game level event.

Notes

This event does NOT suspend user input by default. There is no reason to ever do so.
This event is only executed for one cycle, so any delays in the code are treated like returns.

Animate-Object

event animate AnObject { }

If an animate event is defined, it overrides the interpreter's object animation routine. (Similarly, if the object has an animation handler, the handler overrides this event.)

The purpose of the animation routine is usually just to update frame number of the sprite it is displaying, and the interpreter's routine simply increments the frame. But more intricate user-defined animation routines may use more complex logic.

The reason this is separate from the paint routine is that the object may sometimes be painted without requiring it to move. This happens for instance if there is a menu drawn over the objects.

Notes

This event does NOT suspend user input by default. There is no reason to ever do so.
This event is only executed for one cycle, so any delays in the code are treated like returns.

Mouse-Over-Object

event mouseover AnObject { }

This event is triggered whenever the mouse moves over the specified object.

Mouse-Off-Object

event mouseoff AnObject { }

This event is triggered whenever the mouse off the specified object.

See Also...

Notes

Notes

See Also...