| … | |
… | |
| 140 | |
140 | |
| 141 | ############################################################################# |
141 | ############################################################################# |
| 142 | |
142 | |
| 143 | =head2 ATTACHABLE OBJECTS |
143 | =head2 ATTACHABLE OBJECTS |
| 144 | |
144 | |
| 145 | You can define and attach attachments to each "attachable" object in |
145 | Many objects in crossfire are so-called attachable objects. That means you can |
| 146 | crossfire+ (objects, players, clients, maps and the special "global" |
146 | attach callbacks/event handlers (a collection of which is called an "attachment") |
|
|
147 | to it. All such attachable objects support the following methods. |
|
|
148 | |
| 147 | class). In the following description, CLASS can be any of C<global>, |
149 | In the following description, CLASS can be any of C<global>, C<object> |
| 148 | C<object> C<player>, C<client> or C<map>. |
150 | C<player>, C<client> or C<map> (i.e. the attachable objects in |
|
|
151 | crossfire+). |
| 149 | |
152 | |
| 150 | =over 4 |
153 | =over 4 |
| 151 | |
154 | |
|
|
155 | =item $attachable->attach ($attachment, key => $value...) |
|
|
156 | |
|
|
157 | =item $attachable->detach ($attachment) |
|
|
158 | |
|
|
159 | Attach/detach a pre-registered attachment to a specific object and give it |
|
|
160 | the specified key/value pairs as arguments. |
|
|
161 | |
|
|
162 | Example, attach a minesweeper attachment to the given object, making it a |
|
|
163 | 10x10 minesweeper game: |
|
|
164 | |
|
|
165 | $obj->attach (minesweeper => width => 10, height => 10); |
|
|
166 | |
|
|
167 | =item $bool = $attachable->attached ($name) |
|
|
168 | |
|
|
169 | Checks wether the named attachment is currently attached to the object. |
|
|
170 | |
|
|
171 | =item cf::CLASS->attach ... |
|
|
172 | |
|
|
173 | =item cf::CLASS->detach ... |
|
|
174 | |
|
|
175 | Define an anonymous attachment and attach it to all objects of the given |
|
|
176 | CLASS. See the next function for an explanation of its arguments. |
|
|
177 | |
|
|
178 | You can attach to global events by using the C<cf::global> class. |
|
|
179 | |
|
|
180 | Example, log all player logins: |
|
|
181 | |
|
|
182 | cf::player->attach ( |
|
|
183 | on_login => sub { |
|
|
184 | my ($pl) = @_; |
|
|
185 | ... |
|
|
186 | }, |
|
|
187 | ); |
|
|
188 | |
|
|
189 | Example, attach to the jeweler skill: |
|
|
190 | |
|
|
191 | cf::object->attach ( |
|
|
192 | type => cf::SKILL, |
|
|
193 | subtype => cf::SK_JEWELER, |
|
|
194 | on_use_skill => sub { |
|
|
195 | my ($sk, $ob, $part, $dir, $msg) = @_; |
|
|
196 | ... |
|
|
197 | }, |
|
|
198 | ); |
|
|
199 | |
| 152 | =item cf::CLASS::attachment $name, ... |
200 | =item cf::CLASS::attachment $name, ... |
| 153 | |
201 | |
| 154 | Register an attachment by name through which attachable objects can refer |
202 | Register an attachment by C<$name> through which attachable objects of the |
| 155 | to this attachment. |
203 | given CLASS can refer to this attachment. |
| 156 | |
204 | |
| 157 | =item $bool = $attachable->attached ($name) |
205 | Some classes such as crossfire maps and objects can specify attachments |
|
|
206 | that are attached at load/instantiate time, thus the need for a name. |
| 158 | |
207 | |
| 159 | Checks wether the named attachment is currently attached to the object. |
|
|
| 160 | |
|
|
| 161 | =item $attachable->attach ($attachment, key => $value...) |
|
|
| 162 | |
|
|
| 163 | =item $attachable->detach ($attachment) |
|
|
| 164 | |
|
|
| 165 | Attach/detach a pre-registered attachment either to a specific object |
|
|
| 166 | (C<$attachable>) or all objects of the given class (if C<$attachable> is a |
|
|
| 167 | class in a static method call). |
|
|
| 168 | |
|
|
| 169 | You can attach to global events by using the C<cf::global> class. |
|
|
| 170 | |
|
|
| 171 | These method calls expect any number of the following handler/hook |
208 | These calls expect any number of the following handler/hook descriptions: |
| 172 | descriptions: |
|
|
| 173 | |
209 | |
| 174 | =over 4 |
210 | =over 4 |
| 175 | |
211 | |
| 176 | =item prio => $number |
212 | =item prio => $number |
| 177 | |
213 | |
| … | |
… | |
| 202 | Look for sub functions of the name C<< on_I<event> >> in the given |
238 | Look for sub functions of the name C<< on_I<event> >> in the given |
| 203 | package and register them. Only handlers for eevents supported by the |
239 | package and register them. Only handlers for eevents supported by the |
| 204 | object/class are recognised. |
240 | object/class are recognised. |
| 205 | |
241 | |
| 206 | =back |
242 | =back |
|
|
243 | |
|
|
244 | Example, define an attachment called "sockpuppet" that calls the given |
|
|
245 | event handler when a monster attacks: |
|
|
246 | |
|
|
247 | cf::object::attachment sockpuppet => |
|
|
248 | on_skill_attack => sub { |
|
|
249 | my ($self, $victim) = @_; |
|
|
250 | ... |
|
|
251 | } |
|
|
252 | } |
| 207 | |
253 | |
| 208 | =cut |
254 | =cut |
| 209 | |
255 | |
| 210 | # the following variables are defined in .xs and must not be re-created |
256 | # the following variables are defined in .xs and must not be re-created |
| 211 | our @CB_GLOBAL = (); # registry for all global events |
257 | our @CB_GLOBAL = (); # registry for all global events |
