SDK Event Handlers
Overview
The Active Worlds SDK uses event handlers to communicate with your application whenever something occurs in the Active Worlds environment. Examples of events are:
- An avatar enters the area
- An avatar leaves the area
- Someone says something
- Someone places an object nearby
Typically, applications install handlers at startup for the events they are interested in by calling aw_event_set. If an event occurs for which no handler has been installed, the event is ignored. Thus if an application installs no event handlers, all events are ignored.
Event handlers take no arguments and have no return value. They all have the same form:
void event_handler (void)
{
}
Within the context of the event handler, the current instance is set to the instance for which the event is occurring. Multi-instance applications should use aw_instance to retrieve the current instance handle from within the event handler.
Example: Botware Inc. wants to write a bot that says "hello" to every user who enters their world. Botware's application installs a single event handler for the AW_EVENT_AVATAR_ADD event and writes the event handler function to call aw_say("hello") every time it is called.
Although typically applications receive most events by calling aw_wait, developers should note that events can be triggered any time the SDK is active (i.e. whenever control is passed to a method within the SDK) except for those methods that are documented to "return immediately." For example, it is possible for avatar events to be triggered while waiting for a call to aw_object_add to complete. However, methods which have callbacks installed will not trigger events when called.