Plugin support
==============

Crossfire can be extended through plugins. It's basically a library file, that gets loaded
at server initialization.
A plugin can be hooked to different events, either related to an object or global ones.
(see list later on).

File include/plugin.h contains all definitions a plugin needs to hook to the server.
This should be enough to write plugins.
The best way to find what you need to write is to check this file. You can also check the
Python plugin (plugin/plugin_python.c) which is the most advanced one.

All functions the plugin can access are defined as HOOK_xxx, events are EVENT_xxx.
Check CFW* functions in server/plugins.c for all exported functions and what they do.

Important: a plugin should *never* directly call malloc, free, or any function
manipulating memory if the memory needs to be given to server. This breaks Windows
compatibility. Hooks are provided in case of need.

List of supported events.
=========================

Local events
------------
Those can be attached to a specific object in the game.

APPLY
Tag: event_apply
This event is generated whenever the object is applied or unapplied.

ATTACK
Tag: event_attack
This event is used in two cases:
- bound to a weapon, it is triggered each time the weapon is used to slay
  something; this can typically be used to generate special effects when
  you hit a monster;
- bound to a monster, it is triggered when the monster is attacked.

CLOSE
Tag: event_close
Generated when a container is closed.

DEATH
Tag: event_death
Generated when the object dies.

DROP
Tag: event_drop
Generated when the object is dropped, either on the floor or in a container.

PICKUP
Tag: event_pickup
Generated when the object is picked up.

SAY
Tag: event_say
Generated when someone says something around the object.

STOP
Tag: event_stop
Generated for a thrown object, when the object is stopped for some reason.

TIME
Tag: event_time
Generated each time the object gets an opportunity to move.

THROW
Tag: event_throw
Generated when the object is thrown.

TRIGGER
Tag: event_trigger
Used for various objects, like traps, teleporters or triggers. Generated when
those objects are used (for example, when a player passes through a teleporter).

TIMER
Tag: event_timer
Generated when the timer connected triggered.

Global events
-------------
Those concern the game as a whole or can't be bound to a specific object.
Those events may be "registered" by a plugin (it means that the plugin requests
to get a message each time one of those events happens).

BORN
Generated when a new character is created.

CLOCK
Generated at each game loop.
Warning: When no player is logged, the loop "stops", meaning that clock events
are not generated anymore!

CRASH
Generated when a server crash does occur. It is not a recursive event, so if a
crash occur from *inside* the crash event handling, it is not called a second
time, preventing infinite loops to occur.
Note: This event is not implemented for now.

GDEATH
Generated whenever someone dies.

GKILL
Generated whenever something/someone is killed.

LOGIN
Generated whenever a player logs into the game.

LOGOUT
Generated whenever a player logs out the game.

MAPENTER
Generated whenever someone enters a map.

MAPLEAVE
Generated whenever someone leaves a map.

MAPRESET
Generated each time a map is reset.

REMOVE
Generated when a player character is removed from the game ("quit" command).

SHOUT
Generated whenever someone shouts something.

TELL
Generated whenever someone tells something.

MUZZLE
Generated when a player was muzzled by a DM.

KICK
Generated when a player was kicked by a DM.
