An enhanced version of this documentation is in the plugins.ps file (PostScript format).

The latest version can be found at http://wiki.metalforge.net/doku.php/server_plugin


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).

You should always include two header files in your plugin projects:

- plugin.h, which contains the declaration of most plugin-related constants and
  the required Crossfire includes;
- plugin_common.h (from the plugins/plugin_common directory), which includes the
  necessary support for Crossfire function wrappers.

All your projects should also include plugin_common.c in their build processes;
that source file contains a lot of Crossfire function wrappers you can call.
Do *not* call the callbacks sent by the Crossfire server directly - use what's
provided by plugin_common.c.

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.


The technical documentation is in Developers/plugins.ps, and Developers/cfpython.ps
for Python plugin.

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.
