====== Unified Event System ======
===== Reason =====
These things that exist or are planned all use some event-like constructs:
  * the plugin system
  * connections (i.e. buttons and gates)
  * the callbacks from common to server
  * the proposed refactoring to have "method-like" function pointers for objects and/or object types.

All of those things could be set up to use a unified event/callback system, which would:
  * benefit plugins by making it more flexible
  * get rid of ugly stub hacks
  * reduce repeated effort on the "method-like" system for objects.

===== Proposal =====
  * Event hooks however can be: global, per-map, per-arch, and per-object.
    * All events can be hooked as a global event
    * Events pertaining to a map or an object in a map can be hooked per-map
    * Events pertaining to objects can be hooked as per-arch or per-object
    * This essentially means, everything that can be hooked per-object or per-arch, can be hooked per-map, and everything that can be hooked per-map can be hooked globally.

  * Event hooks can be given priority, with 0 reserved for core server handling of the event. Priority stored in an SINT8, so it can range from -127 to 127, and negative means it happens first. This allows useful things such as setting hooks to run after a player is teleported, or before.

  * The return type of calling an event depends on the event, and some events don't return a value; events act as callbacks of sorts, however multiple callbacks can be assigned to an event.

  * For events that return a value, hooks may or may not return a value. Hooks can be set to active or passive, active ones have a chance of returning a value whereas passive will not. When an active hook returns a value, active hooks of lower priority will not be run, though passive ones still will be.
    * This is to in principal allow hooks that may override the default return of a callback, while also allowing passive hooks to still run both before and after.

  * Events with no return value only allow passive hooks

  * For events without return values, hooks may at runtime opt to force priority 0 (default server internal) or lower, not to run.
    * This is to allow hooks for events without return values, to stop default server code from running. This achieves the same purpose as only the first active event that returns a value, running for events that return a value.

===== Concerns =====
  * Though I wrote the original proposal, I am somewhat concerned that the proposed logic for active/passive hooks and when not to run other hooks is over-engineered, however I cannot think of another method to achieve the same usefulness which is simpler. Does anyone have any suggestions? --- //[[user:rednaxela|Alex Schultz]] 2006/09/24 00:20//

===== More information =====
  * [[http://thread.gmane.org/gmane.games.crossfire.general/2193|Crossfire mailing list: Unified event system]]