server/pod/extensions.pod

=head1 DELIANTRA EXTENSION INTRODUCTION

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