server/pod/extensions.pod

=head1 CROSSFIRE+ EXTENSION INTRODUCTION

In Crossfire+ the plugin/extension and event API was completly rewritten
in Perl and C++. Here is a small guide or introduction on how to
use it.

If you have any questions don't hesitate to contact the developers,
see: http://cf.schmorp.de/contact.shtml


=head2 Extension to <thing> attachments

You can "attach" extensions to global events, to type/subtypes,
to specifix objects, to players and to maps.
On top of that an extension can implement new user commands.

If an extension for example wants to attach itself to all jeweler
skills it has to attach itself like this:

   cf::attach_to_type cf::SKILL, cf::SK_JEWELER,
      on_use_skill => sub {
         ... handling code here ...
      };

This function attaches itself to the type SKILL with the subtype
SK_JEWELER. And everytime someone uses the skill the callback
registered as 'on_use_skill' is called.
Multiple extensions can attach themself to this type, and they
can specify a priority with 'prio => -100' to be executed earlier.

You can also attach a Perl package to the skill like this:

   cf::attach_to_type cf::SKILL, cf::SK_JEWELER,
      package => 'Crossfire::JewelerSkill';

cf::attach_to_objects will attach handlers for events on _all_ objects
in the game, this is mainly for debugging purposes, as it will produce a
high load.

The map attachments work like this:

If an extension wants to attach itself to the 'trigger' event (this is
the event that is generated when a connection is activated (pushed or
released)), it has to do this:

   cf::attach_to_maps
      on_trigger => sub {
         my ($map, $connection, $state) = @_;

         print "CONNECITON TRIGGERED: $connection : $state\n";

         for ($map->get_connection ($connection)) {
            print "connected obj: " . $_->name . "\n";
         }
      };

This small attachment dumps all connection activations and the connected
objects. If this attachment now decides to overwrite connection 10, so that
nothing happens if it is triggered, it has to do this:

   cf::attach_to_maps
      on_trigger => sub {
         my ($map, $connection, $state) = @_;

         if ($connection == 10) {
            cf::override;
            return;     # the idiom 'return cf::override;' is quite common in our code
                        # but i want to empasize that cf::override is just a functioncall
         }
      };

The call of cf::override sets a flag in the event system that will prevent any execution
of further code that handles this event. This way all attachments with 'lower' priority
and the C/C++ code is inhibited/overridden.

=head2 <thing> to extension attachments

The attachments are not limited to 'an extension attaches itself to <...>', a map or an
objects itself can attach to a 'registered' attachment. For example our nice cat which runs
around in scorn and heals people at random has following line in it's archetype:

   Object nekosan
   ...
   attach [["Nekosan"]]
   end

The value of the attach field is a 2 dimensional array in JSON (JavaScript Object Notation)
is a array of arrays which contain following fields:
   [ <attachment name/key>, { <key value pairs of arguments for the attachment> }]

The code side of this looks like this:

   cf::register_attachment "Nekosan", package => __PACKAGE__;

This registeres an attachment under the name/key 'Nekosan' so that objects like our
cat can attach itself.

Where the package defines for example this function:
   sub on_monster_move {
      my ($self, $enemy) = @_;
      ...
   }

$self is a mostly empty object, the attachment object, which is initalized
with the arguments that are given in the 'attach' value, if nekosan would have an
attach field like this:

   attach [["Nekosan", {"foo":"bar"}]]

The attached function can access the value of the key "foo" like this:

    $self->{Nekosan}->{foo}

This way multiple different attachments have a seperate field for storing
their arguments.

=head2 Defining new user commands

If an extension wants to redefine a user command it does it like this:

   cf::register_command invite => 10, sub {
      my ($who, $args) = @_;
      ...
   }

This registers the 'invite' command with the execution time of 10. The
arguments to the function are ($who, $args), where $who is the player
and $args the argument string to the command.

=head2 Adding event invocations to the C++ code

There are already a lot of events implemented, look in the L<events.pod> for
a reference of existing events. But when you need a new event, here
is how to do add it:

Here an example for move_trigger in move_apply ():

Add a line to doc/events.pod with documentation looking like this:

   =head3 move_trigger (object victim originator -- )

   Invoked whenever a trap-like B<object> has been activated, usually by
   moving onto it. This includes not just traps, but also buttons, holes,
   signs and similar stuff.

And put some lines like this to move_apply:

   if (INVOKE_OBJECT (MOVE_TRIGGER, trap, ARG_OBJECT (victim), ARG_OBJECT (originator)))
      goto leave;

This invokes all attachments that are interested in the object event MOVE_TRIGGER, with
the object being 'trap' and the arguments victim and originator. This is all C++ code
that has to be added when one wants to add an event. 'make' will update include/eventinc.h
from the events.pod automatically when building.

=head2 Resources / See also

Here is the documentation for all this, which is maybe partly unfinished. But there
are also a lot of examples:

=over 4

=item lib/cf.pm

Has some documentation of the attachment API

=item pod/events.pod

A reference for all existing events

=item Examples

Examples can be found in http://cvs.schmorp.de/cf.schmorp.de/maps/perl/

=item NPC_Dialogue.pod in maps/perl/

The NPC dialogue system might also be interesting: http://cf.schmorp.de/doc/development/NPC_Dialogue.html
Revision:	1.2
Committed:	Sat Sep 9 23:22:06 2006 UTC (17 years, 8 months ago) by elmex
Branch:	MAIN
CVS Tags:	rel-2_2, rel-2_3, rel-2_0, rel-2_1
Changes since 1.1:	+4 -4 lines
Log Message:	a => an
#	User	Rev	Content
1	elmex	1.1	=head1 CROSSFIRE+ EXTENSION INTRODUCTION
2
3			In Crossfire+ the plugin/extension and event API was completly rewritten
4			in Perl and C++. Here is a small guide or introduction on how to
5			use it.
6
7			If you have any questions don't hesitate to contact the developers,
8			see: http://cf.schmorp.de/contact.shtml
9
10
11			=head2 Extension to <thing> attachments
12
13			You can "attach" extensions to global events, to type/subtypes,
14			to specifix objects, to players and to maps.
15	elmex	1.2	On top of that an extension can implement new user commands.
16	elmex	1.1
17	elmex	1.2	If an extension for example wants to attach itself to all jeweler
18	elmex	1.1	skills it has to attach itself like this:
19
20			cf::attach_to_type cf::SKILL, cf::SK_JEWELER,
21			on_use_skill => sub {
22			... handling code here ...
23			};
24
25			This function attaches itself to the type SKILL with the subtype
26			SK_JEWELER. And everytime someone uses the skill the callback
27			registered as 'on_use_skill' is called.
28			Multiple extensions can attach themself to this type, and they
29			can specify a priority with 'prio => -100' to be executed earlier.
30
31			You can also attach a Perl package to the skill like this:
32
33			cf::attach_to_type cf::SKILL, cf::SK_JEWELER,
34			package => 'Crossfire::JewelerSkill';
35
36			cf::attach_to_objects will attach handlers for events on _all_ objects
37			in the game, this is mainly for debugging purposes, as it will produce a
38			high load.
39
40			The map attachments work like this:
41
42	elmex	1.2	If an extension wants to attach itself to the 'trigger' event (this is
43	elmex	1.1	the event that is generated when a connection is activated (pushed or
44			released)), it has to do this:
45
46			cf::attach_to_maps
47			on_trigger => sub {
48			my ($map, $connection, $state) = @_;
49
50			print "CONNECITON TRIGGERED: $connection : $state\n";
51
52			for ($map->get_connection ($connection)) {
53			print "connected obj: " . $_->name . "\n";
54			}
55			};
56
57			This small attachment dumps all connection activations and the connected
58			objects. If this attachment now decides to overwrite connection 10, so that
59			nothing happens if it is triggered, it has to do this:
60
61			cf::attach_to_maps
62			on_trigger => sub {
63			my ($map, $connection, $state) = @_;
64
65			if ($connection == 10) {
66			cf::override;
67			return; # the idiom 'return cf::override;' is quite common in our code
68			# but i want to empasize that cf::override is just a functioncall
69			}
70			};
71
72			The call of cf::override sets a flag in the event system that will prevent any execution
73			of further code that handles this event. This way all attachments with 'lower' priority
74			and the C/C++ code is inhibited/overridden.
75
76			=head2 <thing> to extension attachments
77
78			The attachments are not limited to 'an extension attaches itself to <...>', a map or an
79			objects itself can attach to a 'registered' attachment. For example our nice cat which runs
80			around in scorn and heals people at random has following line in it's archetype:
81
82			Object nekosan
83			...
84			attach [["Nekosan"]]
85			end
86
87			The value of the attach field is a 2 dimensional array in JSON (JavaScript Object Notation)
88			is a array of arrays which contain following fields:
89			[ <attachment name/key>, { <key value pairs of arguments for the attachment> }]
90
91			The code side of this looks like this:
92
93			cf::register_attachment "Nekosan", package => __PACKAGE__;
94
95			This registeres an attachment under the name/key 'Nekosan' so that objects like our
96			cat can attach itself.
97
98			Where the package defines for example this function:
99			sub on_monster_move {
100			my ($self, $enemy) = @_;
101			...
102			}
103
104			$self is a mostly empty object, the attachment object, which is initalized
105			with the arguments that are given in the 'attach' value, if nekosan would have an
106			attach field like this:
107
108			attach [["Nekosan", {"foo":"bar"}]]
109
110			The attached function can access the value of the key "foo" like this:
111
112			$self->{Nekosan}->{foo}
113
114			This way multiple different attachments have a seperate field for storing
115			their arguments.
116
117			=head2 Defining new user commands
118
119	elmex	1.2	If an extension wants to redefine a user command it does it like this:
120	elmex	1.1
121			cf::register_command invite => 10, sub {
122			my ($who, $args) = @_;
123			...
124			}
125
126			This registers the 'invite' command with the execution time of 10. The
127			arguments to the function are ($who, $args), where $who is the player
128			and $args the argument string to the command.
129
130			=head2 Adding event invocations to the C++ code
131
132			There are already a lot of events implemented, look in the L<events.pod> for
133			a reference of existing events. But when you need a new event, here
134			is how to do add it:
135
136			Here an example for move_trigger in move_apply ():
137
138			Add a line to doc/events.pod with documentation looking like this:
139
140			=head3 move_trigger (object victim originator -- )
141
142			Invoked whenever a trap-like B<object> has been activated, usually by
143			moving onto it. This includes not just traps, but also buttons, holes,
144			signs and similar stuff.
145
146			And put some lines like this to move_apply:
147
148			if (INVOKE_OBJECT (MOVE_TRIGGER, trap, ARG_OBJECT (victim), ARG_OBJECT (originator)))
149			goto leave;
150
151			This invokes all attachments that are interested in the object event MOVE_TRIGGER, with
152			the object being 'trap' and the arguments victim and originator. This is all C++ code
153			that has to be added when one wants to add an event. 'make' will update include/eventinc.h
154			from the events.pod automatically when building.
155
156			=head2 Resources / See also
157
158			Here is the documentation for all this, which is maybe partly unfinished. But there
159			are also a lot of examples:
160
161			=over 4
162
163			=item lib/cf.pm
164
165			Has some documentation of the attachment API
166
167			=item pod/events.pod
168
169			A reference for all existing events
170
171			=item Examples
172
173			Examples can be found in http://cvs.schmorp.de/cf.schmorp.de/maps/perl/
174
175			=item NPC_Dialogue.pod in maps/perl/
176
177			The NPC dialogue system might also be interesting: http://cf.schmorp.de/doc/development/NPC_Dialogue.html