[Main page] [Overview]     /concepts /events

---

CONCEPT
events

DESCRIPTION

Whenever in-game actions occur, messages are sent to all other
objects near the event actor and all objects contained by them.
This allows objects to cancel, modify, or react to such events
or to even handle them completely for themselves instead of
letting the default handler care about the action.

An even consists of a string - the event type - and an attached
mapping with further data about the event.

Events are sent by calling the "send_event" method in the object
causing the event. Afterwards, nearby objects are gathered and
the method "receives_<event_type>_events" is called to check
whether you want to receive that event (returns true).

All event receivers then have their "<event_type>_canceller"
method called and the event data is sent along. Each canceller
has the possibility to completely cancel the event (by returning
true) or to modify the event data by changing values in the
mapping.

If the event was cancelled, afterwards "<event_type>_cancelled"
is called in all objects.

If the event was not cancelled, the method "<event_type>_handler"
is called to actually fullfill the event and afterwards
"<event_type>_handled" is called in all objects to give them a
chance to react to the event.

EXAMPLE

If a player moves around using the "go" verb a "move" event
is generated with the fields E_ORIGIN (the old location) and
E_TARGET (the new location).

The event receivers are filtered by calling

ob->receives_move_events()

on all objects. Any objects which return true for that method
now receive the event.

First

ob->move_canceller(mapping event, object player)

is called, afterwards, depending on whether the event was
cancelled or not

ob->move_cancelled(mapping event, object player, object canceller)

is called or

ob->move_handler( mapping event, object player);
ob->move_handled( mapping event, object player)

SEE ALSO
std/base/send_event, event