1 |
THE PYTHON PLUGIN, VERSION 2.0 |
2 |
=============================== |
3 |
|
4 |
What is the Python Plugin ? |
5 |
--------------------------- |
6 |
It is a plugin part of the Crossfire server that allows map-makers to create |
7 |
object behaviors using Python scripts instead of having to hardcode them in C. |
8 |
|
9 |
|
10 |
Converting from CFPython 0.x and 1.0 |
11 |
------------------------------------ |
12 |
A lot of things have changed which hopefully make your Python coder's life a |
13 |
little more comfortable. |
14 |
|
15 |
1. The library name is now "Crossfire", instead of the previous "CFPython". No, |
16 |
that's not to annoy you without purpose. It will force you to think about |
17 |
reading your old Python code and make the necessary conversions. |
18 |
2. Objects and Maps are now wrapped into Python objects. It means that instead |
19 |
of writing "CFPython.Teleport(object,map,x,y)", you'll now have to write |
20 |
"object.Teleport(map,x,y)". It is somewhat more logical and contributes to |
21 |
cleaner Python code. |
22 |
3. The plugin event hook mechanism is now based on event objects contained in |
23 |
WhoAmI's inventory. |
24 |
|
25 |
To make the transition as easy as possible, most functions of CFPython were |
26 |
converted using the following rules: |
27 |
- If the function was a getter/setter of an object or map attribute, it is now |
28 |
available as a Python object attribute. |
29 |
Examples: print CFPython.GetDamage(object) --> print object.Damage |
30 |
CFPython.SetDamage(object, value) --> object.Damage = value |
31 |
- If the function was an action performed by an object/a map, or related to a |
32 |
specific object/map, it is now available as a Python object method. |
33 |
Examples: CFPython.Take(object, what) --> object.Take(what) |
34 |
CFPython.CheckMap(what, map, x, y) --> map.Check(what,x,y) |
35 |
|
36 |
Only a few methods/attributes have changed names (this is the case for the seven |
37 |
base attributes STR,DEX,CON,INT,WIS,POW,CHA for example). |
38 |
|
39 |
Note that although it may seem that converting your old scripts to the new |
40 |
format will be a huge job, it is rather straightforward in most cases. It only |
41 |
took me an afternoon to convert and test all the scripts supplied with the |
42 |
default map set, and I wasn't even their original author. |
43 |
|
44 |
|
45 |
How do I hook a script to an object? |
46 |
------------------------------------ |
47 |
|
48 |
There are special archetypes named event_xxx available. You need to put those in |
49 |
the inventory of the objects to which you want to connect your script. |
50 |
|
51 |
Some fields of the event_xxx archetypes have a special meaning: |
52 |
|
53 |
- name: all parameters you want to pass to the scripts should go there; |
54 |
- title: this is the plugin identifier. For the Python plugin, it is "Python" |
55 |
(without the quotes); |
56 |
- slaying: the name of the script file to execute when the event is triggered. |
57 |
Note that this name is relative to the map base directory. |
58 |
|
59 |
Example: |
60 |
|
61 |
arch event_apply |
62 |
name parms |
63 |
title Python |
64 |
slaying test.py |
65 |
end |
66 |
|
67 |
The event will be triggered when the container object is applied and will run |
68 |
share/crossfire/maps/test.py, passing "parms" as a parameter string to the |
69 |
script. |
70 |
|
71 |
You of course need to write some Python code too... You do as usual, but |
72 |
remember to add an "import Crossfire" to make all crossfire-specific functions |
73 |
available in your script. |
74 |
|
75 |
|
76 |
How do I hook a global event? |
77 |
----------------------------- |
78 |
|
79 |
Each global event is bound to a specific Python script file. Those files are |
80 |
located in the python/events/ subdirectory of your crossfire map directory. |
81 |
They have specific names, too: python_xxx.py, where xxx is the name of the |
82 |
global event you want to intercept. For example, a script that should be run |
83 |
each time a player logs in ("login" event) should be named python_login.py. |
84 |
|
85 |
|
86 |
What functions are currently supported? |
87 |
--------------------------------------- |
88 |
|
89 |
A complete list of those functions is given below. |
90 |
|
91 |
Last count (2005-03-06) result: 217 functions (not including attack type/event |
92 |
type wrapper functions). This of course does not include all the Python |
93 |
functions, just the crossfire-specific ones. |
94 |
|
95 |
In the following, I use the following type naming convention: |
96 |
int : An integer. |
97 |
long : A long. |
98 |
float : A float. |
99 |
object: A crossfire object. (In fact, it is a long). |
100 |
map : A crossfire map. (In fact, it is a long). |
101 |
string: A character string. |
102 |
|
103 |
1. Global Methods |
104 |
+++++++++++++++++ |
105 |
|
106 |
Those are provided by the Crossfire library directly, so to call them, you have |
107 |
to write something like: Crossfire.Method(). |
108 |
|
109 |
ConfigDirectory() (1.x name: GetConfigurationDirectory()) |
110 |
Return the name of the base directory containing Crossfire configuration |
111 |
files. |
112 |
Returns the directory name as a string. |
113 |
|
114 |
DirectionN() |
115 |
Wrapper for the North direction. |
116 |
Return value: an integer representing the direction. |
117 |
|
118 |
DirectionNE() |
119 |
Wrapper for the North-East direction. |
120 |
Return value: an integer representing the direction. |
121 |
|
122 |
DirectionE() |
123 |
Wrapper for the East direction. |
124 |
Return value: an integer representing the direction. |
125 |
|
126 |
DirectionSE() |
127 |
Wrapper for the South-East direction. |
128 |
Return value: an integer representing the direction. |
129 |
|
130 |
DirectionS() |
131 |
Wrapper for the South direction. |
132 |
Return value: an integer representing the direction. |
133 |
|
134 |
DirectionSW() |
135 |
Wrapper for the South-West direction. |
136 |
Return value: an integer representing the direction. |
137 |
|
138 |
DirectionW() |
139 |
Wrapper for the West direction. |
140 |
Return value: an integer representing the direction. |
141 |
|
142 |
DirectionNW() |
143 |
Wrapper for the North-West direction. |
144 |
Return value: an integer representing the direction. |
145 |
|
146 |
2. Object-Specific Methods |
147 |
++++++++++++++++++++++++++ |
148 |
|
149 |
Those are provided by the Python object wrapper. |
150 |
|
151 |
ActivateRune(object activator) |
152 |
Trigger the rune. Note that both the rune and its activator must be in the |
153 |
same or in adjacent tiles of the same map. |
154 |
Does not return a value. |
155 |
|
156 |
Example: |
157 |
who = Crossfire.WhoIsActivator() |
158 |
rune = who.Map.CreateObject("rune_burning_hands", who.X, who.Y) |
159 |
rune.ActivateRune(who) |
160 |
|
161 |
Apply(object what, int flags) |
162 |
Make the object apply an object 'what'. The applying object can be a |
163 |
player or a monster. The applied object need not be on the same tile as |
164 |
the applier. 'flags' specifies how to apply the object: |
165 |
- 0=toggle (apply/unapply) the object |
166 |
- 1=always apply the object |
167 |
- 2=always unapply the object |
168 |
Additionally, you can specify some modifier bits: |
169 |
- 16=do not merge an unapplied object with other objects |
170 |
- 32=unapply the item even if it is cursed |
171 |
- 64=print the object name but do not apply/unapply it |
172 |
|
173 |
Return value: integer denoting the result: |
174 |
- 0=player or monster can't apply an object of that type |
175 |
- 1=object has been applied, or there was an error applying the object |
176 |
- 2=objects of that type can't be applied if not in inventory |
177 |
|
178 |
Example: |
179 |
who = Crossfire.WhoIsActivator() |
180 |
|
181 |
# create and apply a trigger object |
182 |
trigger = who.Map.CreateObject("trigger", who.X, who.Y) |
183 |
result = who.Apply(trigger, 0); # returns 1 |
184 |
|
185 |
# create and apply an amulet |
186 |
food = who.Map.CreateObject("amulet of sustenance", who.X, who.Y) |
187 |
result = who.Apply(food, 0); # returns 2 |
188 |
|
189 |
# create and apply/unapply a cursed shield |
190 |
shield = who.CreateObject("small shield") |
191 |
shield.Cursed = 1; |
192 |
result = who.Apply(shield, 1); # returns 1 |
193 |
result = who.Apply(shield, 2); # returns 1 (it does not unapply the item) |
194 |
result = who.Apply(shield, 2|32); # returns 1 |
195 |
|
196 |
LearnSpell(object spell) (1.x name: AcquireSpell) |
197 |
Learn the spell identified by a spell object. |
198 |
Does not return a value. |
199 |
|
200 |
Example: |
201 |
who = Crossfire.WhoIsActivator() |
202 |
spell = Crossfire.CreateObjectByName("spell_large_fireball") |
203 |
who.LearnSpell(spell) |
204 |
spell.Remove() |
205 |
|
206 |
Say(message text) |
207 |
Say 'text'. |
208 |
Does not return a value. |
209 |
|
210 |
3. Object-Specific Attributes |
211 |
+++++++++++++++++++++++++++++ |
212 |
|
213 |
CanCastSpell |
214 |
Test if the object can cast spells. |
215 |
Return value: test result as an integer - 0 if and only if false. |
216 |
|
217 |
CanPassThru |
218 |
Test if the object has the 'pass through' ability. |
219 |
Return value: test result as an integer - 0 if and only if false. |
220 |
|
221 |
CanPickUp |
222 |
Test if the object can pick up stuff. |
223 |
Return value: test result as an integer - 0 if and only if false. |
224 |
|
225 |
CanRoll |
226 |
Test if the object can roll. |
227 |
Return value: test result as an integer - 0 if and only if false. |
228 |
|
229 |
CanSeeInDark |
230 |
Test if object has got infravision capabilities. |
231 |
Return value: test result as an integer - 0 if and only if false. |
232 |
|
233 |
CanSeeInvisible |
234 |
Test if the object can see invisible things. |
235 |
Return value: test result as an integer - 0 if and only if false. |
236 |
|
237 |
CanUseArmour |
238 |
Test if the object can wear armor. |
239 |
Return value: test result as an integer - 0 if and only if false. |
240 |
|
241 |
CanUseBow |
242 |
Test if the object can use a bow. |
243 |
Return value: test result as an integer - 0 if and only if false. |
244 |
|
245 |
CanUseHorn |
246 |
Test if the object can use a horn (and other musical instruments). |
247 |
Return value: test result as an integer - 0 if and only if false. |
248 |
|
249 |
CanUseRing |
250 |
Test if the object can use rings. |
251 |
Return value: test result as an integer - 0 if and only if false. |
252 |
|
253 |
CanUseRod |
254 |
Test if the object can use magical rods. |
255 |
Return value: test result as an integer - 0 if and only if false. |
256 |
|
257 |
CanUseScroll |
258 |
Test if the object can read scrolls. |
259 |
Return value: test result as an integer - 0 if and only if false. |
260 |
|
261 |
CanUseSkill |
262 |
Test if the object can use skills. |
263 |
Return value: test result as an integer - 0 if and only if false. |
264 |
|
265 |
CanUseWand |
266 |
Test if the object can use a magical wand. |
267 |
Return value: test result as an integer - 0 if and only if false. |
268 |
|
269 |
CanUseWeapon |
270 |
Test if the object can use a weapon. |
271 |
Return value: test result as an integer - 0 if and only if false. |
272 |
|
273 |
|
274 |
4. Map-Specific Methods |
275 |
+++++++++++++++++++++++ |
276 |
|
277 |
Those are provided by the Python map wrapper. |
278 |
|
279 |
5. Map-Specific Attributes |
280 |
++++++++++++++++++++++++++ |
281 |
|
282 |
|
283 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
284 |
TODO: Finish converting the 1.x docs. |
285 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
286 |
|
287 |
|
288 |
A |
289 |
AttackTypeXxx() |
290 |
Wrapper for attack type Xxx. Possible values for Xxx are: Acid Blind |
291 |
Cancellation Chaos Cold Confusion Counterspell Death Depletion Disease Drain |
292 |
Electricity Fear Fire Ghosthit Godpower HolyWord LifeStealing Magic Paralyze |
293 |
Physical Poison Slow TurnUndead Weaponmagic. |
294 |
Return value: an integer representing the attack type. |
295 |
|
296 |
B |
297 |
BlocksView(object obj) |
298 |
Check if 'obj' can block the line-of-sight. |
299 |
Return value: test result as in integer - 0 if and only if false. |
300 |
|
301 |
C |
302 |
|
303 |
CastAbility(object who, object caster, string spell, int direction, string |
304 |
options) |
305 |
Make the object 'caster' cast a 'spell'. 'who' is the owner of the casting |
306 |
object; 'who' and 'caster' may be the same item. The spell is identified by |
307 |
the spell name and cast into the given direction. 'options' can hold some |
308 |
options. |
309 |
Does not return a value. |
310 |
|
311 |
Note: to cast a spell by a spell object, use CastSpell(). |
312 |
|
313 |
Example: |
314 |
who = CFPython.WhoIsActivator() |
315 |
caster = CFPython.CreateObjectInside("horn of Fire", who) |
316 |
CFPython.CastAbility(who, caster, "spell_firebolt", CFPython.DirectionE(), "") |
317 |
|
318 |
Example: |
319 |
who = CFPython.WhoIsActivator() |
320 |
CFPython.CastAbility(who, who, "spell_create_food", 0, "booze") |
321 |
|
322 |
CastSpell(object who, object spell, int direction, string options) |
323 |
|
324 |
Make 'who' cast a spell, identified by a spell object, into one direction. |
325 |
'options' can hold some options. |
326 |
Does not return a value. |
327 |
|
328 |
Note: this function is similar to CastAbility() except that a spell object |
329 |
(instead of a spell name) is used and that 'caster' is set to 'who'. |
330 |
|
331 |
Note: the spell will be cast even if the 'who' has not sufficient spell |
332 |
points; in fact, 'who' may end with negative spell points. |
333 |
|
334 |
Example: |
335 |
# make the activator cast a large fireball (if he knows that spell) |
336 |
who = CFPython.WhoIsActivator() |
337 |
spell = CFPython.DoKnowSpell(who, "large fireball") |
338 |
if spell: CFPython.CastSpell(who, spell, CFPython.DirectionSE(), "") |
339 |
|
340 |
CheckArchInventory(object who, string arch_name) |
341 |
Check if 'who' has an object with the archetype 'arch_name' in his inventory. |
342 |
Return value: the first matching object or 0 if the archetype was not found. |
343 |
|
344 |
Example: |
345 |
who = CFPython.WhoIsActivator() |
346 |
obj = CFPython.CheckArchInventory(who, 'key2') |
347 |
if obj: CFPython.Write(CFPython.GetName(obj), who) |
348 |
|
349 |
CheckInventory(object who, string name) |
350 |
Check if 'who' has an object named 'name' in his inventory. It first checks |
351 |
for any item with a matching archetype name, then for an object with a name |
352 |
beginning with 'name'. |
353 |
Return value: the matching object or 0 if no object was found. |
354 |
|
355 |
CheckInvisibleObjectInside(object who, string id) |
356 |
Check for the existence of an force object with a slaying field 'id' inside |
357 |
'who'. |
358 |
Return value: The force object found or 0. |
359 |
|
360 |
CheckMap(string what, map map, (int x, int y)) |
361 |
Check for an item with the archetype name 'what' in a map at a given |
362 |
position. The function works for tiled maps. |
363 |
Return value: The object found or 0. |
364 |
|
365 |
CheckTrigger(object trigger, object what) |
366 |
Try to trigger an object 'trigger' by 'what'. The object 'what' may be |
367 |
destroyed. (For example if 'trigger' is an altar.) |
368 |
Does not return a value. |
369 |
|
370 |
Example: |
371 |
# create and trigger an altar |
372 |
altar = CFPython.CreateObject("altar_trigger", (0, 0)) |
373 |
food = CFPython.CreateObject("food", (1, 0)) |
374 |
CFPython.SetQuantity(food, 5) |
375 |
CFPython.CheckTrigger(altar, food) |
376 |
|
377 |
CostFlagXxx() |
378 |
Wrapper for flags to use as the third parameter of GetObjectCost(). You must |
379 |
always choose one of FBuy, FSell, or FTrue. You may add any other flags as |
380 |
well. Possible Values for Xxx are: |
381 |
- FBuy: item value for a player buying the item |
382 |
- FSell: item value for a player selling the item |
383 |
- FTrue: true value of the item |
384 |
- FNoBargain: disable modifications due to bargaining skill |
385 |
- FIdentified: pretend the item as identified |
386 |
- FNotCursed: pretend the item as not cursed |
387 |
Return value: integer integer representing the flag. |
388 |
|
389 |
CreateInvisibleObjectInside(object where, string name) |
390 |
Create a force object with a slaying field of 'name'. The object is placed in |
391 |
the inventory of 'where'. |
392 |
Return value: the created force object. |
393 |
|
394 |
Note: The statement "obj = CFPython.CreateInvisibleObjectInside(who, 'slay')" |
395 |
is basically the same as: |
396 |
obj = CFPython.CreateObjectInside('force', who) |
397 |
CFPython.SetSlaying(obj, 'slay') |
398 |
CFPython.SetSpeed(obj, 0) |
399 |
|
400 |
CreateObject(string name, (int x, int y)[, string map]) |
401 |
Create an object from the archetype 'name', or with the name 'name'. Insert |
402 |
it at position (x,y) in the map. If map is omitted, it defaults to |
403 |
GetMap(WhoAmI()). |
404 |
Return value: the created object. Note that the returned object may have |
405 |
nrof>1 if the new item has been merged with other objects. |
406 |
|
407 |
Note: Not all types of objects can be created; for example, objects of type |
408 |
PLAYER will crash the server. |
409 |
|
410 |
Note: Not all kinds of objects are created correctly; for example, currently |
411 |
a "horn of Fire" cannot be created: it creates a working horn but it is blue |
412 |
with message "Putting this shell to you ear, you hear a strange and haunting |
413 |
melody" and it is god-given. |
414 |
|
415 |
Note: This function does not work correctly if the object contains a |
416 |
"randomitems" field in the archetype. |
417 |
|
418 |
CreateObjectInside(string name, object where) |
419 |
Create an object from the archetype 'name', or with the name 'name'. Insert |
420 |
it into the inventory of 'where'. |
421 |
Return value: the created object |
422 |
|
423 |
Note: see CreateObject() |
424 |
|
425 |
Examples: |
426 |
CFPython.CreateObjectInside("stylus", CFPython.WhoAmI()) # archetype name |
427 |
CFPython.CreateObjectInside("writing pen", CFPython.WhoAmI()) # object name |
428 |
CFPython.CreateObjectInside("levitation boots of mobility", CFPython.WhoAmI()) # artifact object |
429 |
|
430 |
D |
431 |
DecreaseObjectNr(object ob, int nrof) |
432 |
Remove the given number of items from ob. If nrof is equal or more |
433 |
than the items left in ob, ob is removed. |
434 |
Return value: the object ob if some items are still remaining or 0 if all |
435 |
objects are removed. |
436 |
|
437 |
DoKnowSpell(object who, string spell) |
438 |
Check if 'who' knows the spell by the name of 'spell'. |
439 |
Returns the spell object if 'who' knows the spell or 0 if not. |
440 |
|
441 |
Example: see CastSpell() |
442 |
|
443 |
Drop(object who, string name) |
444 |
Let 'who' drop the items named 'name'. |
445 |
Does not return a value. |
446 |
|
447 |
E |
448 |
EventXxx() |
449 |
Wrapper for event type Xxx. Possible values are: Apply Attack Close Death |
450 |
Drop Pickup Say Stop Throw Time Timer Trigger. |
451 |
Return value: an integer representing the event type. |
452 |
|
453 |
F |
454 |
FindPlayer(string name) |
455 |
Check for a player with the given name. Note: the comparison is |
456 |
case-sensitive and does not allow for partial matches. |
457 |
Return value: the player object or 0 if not found. |
458 |
|
459 |
FixObject(object who) |
460 |
Update all abilities granted by applied objects in the inventory of the |
461 |
given object. This functions starts from base values (archetype or player |
462 |
object) and then adjusts them according to what the object has equipped. |
463 |
Does not return a value. |
464 |
|
465 |
ForgetSpell(object who, string spell) |
466 |
Cause who to forget the spell named 'spell'. who must be a player. |
467 |
Does not return a value. |
468 |
|
469 |
Example: |
470 |
who = CFPython.WhoIsActivator() |
471 |
CFPython.ForgetSpell(who, "large fireball") |
472 |
|
473 |
G |
474 |
GetAC(object who) |
475 |
Get the Armor Class coefficient associated with the given object. |
476 |
Returns the armor class coefficient as an integer. |
477 |
|
478 |
GetArchType(object who) |
479 |
Get the archtype name of an object. |
480 |
Returns the archtype as a string. |
481 |
|
482 |
GetAttackType(object who) |
483 |
Determine the attack type of an object. |
484 |
Returns the attack type as an integer. |
485 |
|
486 |
GetCharisma(object who) |
487 |
Get the Charisma value of the given object. |
488 |
Returns the charisma value as an integer. |
489 |
|
490 |
GetConstitution(object who) |
491 |
Get the Constitution value of the given object. |
492 |
Returns the constitution value as an integer. |
493 |
|
494 |
GetDamage(object who) |
495 |
Get the amount of damage associated with the given object. |
496 |
Returns the damage value as an integer. |
497 |
|
498 |
GetDataDirectory() |
499 |
Return the name of the base directory containing the Crossfire read only data |
500 |
files. |
501 |
Returns the directory name as a string. |
502 |
|
503 |
GetDexterity(object who) |
504 |
Get the Dexterity value of the given object. |
505 |
Returns the dexterity value as an integer. |
506 |
|
507 |
GetDirection(object who) |
508 |
Determine the direction an turnable object 'who' is currently moving. Use |
509 |
IsTurnable(who) to determine if an object is turnable. |
510 |
Returns the direction as an integer. |
511 |
|
512 |
GetEventHandler(object who, int event) |
513 |
Get the event handler of 'who' for the event number 'event'. The parameter |
514 |
'event' should be a value returned by EventXxx(). |
515 |
Returns the event handler name as a string or no object if the handler is not |
516 |
used. |
517 |
|
518 |
GetEventOptions(object who, int event) |
519 |
Get the event options of 'who' for the event number 'event'. The parameter |
520 |
'event' should be a value returned by EventXxx(). |
521 |
Returns the event options as a string or no object if the handler is not |
522 |
used. |
523 |
|
524 |
GetEventPlugin(object who, int event) |
525 |
Get the event plugin name of 'who' for the event number 'event'. The |
526 |
parameter 'event' should be a value returned by EventXxx(). |
527 |
Returns the event options as a string or no object if the handler is not |
528 |
used. |
529 |
|
530 |
GetExperience(object who) |
531 |
Get the amount of experience associated with the object. |
532 |
Returns the event options as a long. |
533 |
|
534 |
GetFacing(object who) |
535 |
Determine the direction an turnable object 'who' is currently facing. It |
536 |
is similar to GetDirection except it works for non-moving objects too. See |
537 |
GetDirection for details. |
538 |
Returns the direction as an integer. |
539 |
|
540 |
GetFirstObjectOnSquare(map map, int x, int y) |
541 |
Get the first object at position (x,y) in the map 'map'. Use |
542 |
GetPreviousObject() to find the next item(s). |
543 |
Returns the object or 0 if the position is empty. |
544 |
|
545 |
GetFood(object who) |
546 |
Get the food level of the given object. |
547 |
Returns the food level as an integer. |
548 |
|
549 |
GetGod(object who) |
550 |
Get the name of the god associated with the given object. Usually, this will |
551 |
be the god 'who' is worshipping. |
552 |
Return value: the god name as a string or no object if 'who' has no god. |
553 |
|
554 |
GetGrace(object obj) |
555 |
Get the grace amount of the given object. |
556 |
Returns the grace amount as an integer. |
557 |
|
558 |
GetHP(object who) |
559 |
Get the amount of Hit Points associated with the given object. |
560 |
Returns the amount of hit points as an integer. |
561 |
|
562 |
GetHumidity(int x, int y, map map) |
563 |
Get the humidity level of a given square of a map. |
564 |
Returns the humidity level as an integer. |
565 |
|
566 |
Remark: not implemented. Always returns zero. |
567 |
|
568 |
GetIntelligence(object who) |
569 |
Get the Intelligence value of the given object. |
570 |
Returns the intelligence value as an integer. |
571 |
|
572 |
GetInternalName(object who) |
573 |
Get the name of 'who' without any modifications. |
574 |
Returns the object name as a string. |
575 |
|
576 |
GetInventory(object who) |
577 |
Get the first inventory object of 'who'. Use GetNextObject() to find the next |
578 |
inventory objects. |
579 |
Returns the object or 0 if the inventory is empty. |
580 |
|
581 |
GetIP(object player) |
582 |
Get the ip address of 'player'. The given object should be a player object. |
583 |
Returns the ip address as a string or no value if the object is not a player |
584 |
object. |
585 |
|
586 |
GetLastGrace(object who) |
587 |
Get the last_grace parameter value associated with the given object. |
588 |
Returns the last_grace value as an integer. |
589 |
|
590 |
GetLastSP(object who) |
591 |
Get the last_sp parameter value associated with the given object. |
592 |
Returns the last_sp value as an integer. |
593 |
|
594 |
GetLevel(object who) |
595 |
Get the level of a given object. |
596 |
Returns the level as an integer. |
597 |
|
598 |
GetLocalDirectory() |
599 |
Return the name of the base directory containing the Crossfire read-write |
600 |
data files. |
601 |
Returns the directory name as a string. |
602 |
|
603 |
GetMap(object who) |
604 |
Determine the map the object 'who' is currently in. |
605 |
Returns the map as a map or 0 if the items is not part of a map. |
606 |
|
607 |
GetMapDirectory() |
608 |
Return the name of the base directory containing the Crossfire maps. You need |
609 |
to concatenate the result with the value returned by GetDataDirectory() to |
610 |
get an absolute path. |
611 |
Returns the directory as a string. |
612 |
|
613 |
GetMapHeight(map map) |
614 |
Get the height (the number of tiles) of a map. |
615 |
Returns the height as an integer. |
616 |
|
617 |
GetMapObject() |
618 |
This function should not be used anymore. It always throws an exception. |
619 |
|
620 |
GetMapPath(map map) |
621 |
Get the path name of the map. |
622 |
Returns the path name as a string. |
623 |
|
624 |
GetMapWidth(map map) |
625 |
Get the width (the number of tiles) of a map. |
626 |
Returns the width as an integer. |
627 |
|
628 |
GetMaxHP(object who) |
629 |
Get the maximum amount of Hit Points the given object can get. |
630 |
Returns the amount of hit points as an integer. |
631 |
|
632 |
GetMaxSP(object who) |
633 |
Get the maximum amount of mana the given object can get. |
634 |
Returns the maximum amount of mana as an integer. |
635 |
|
636 |
GetMessage(object obj) |
637 |
Get the message contained in the specified object. The message is what |
638 |
appears inside msg...endmsg tags. |
639 |
Returns the message as a string. |
640 |
|
641 |
GetName(object who) |
642 |
Get the 'clear name' of the given object. |
643 |
Returns the name as a string. |
644 |
|
645 |
GetNextObject(object obj) |
646 |
Get the next object below 'obj'. |
647 |
Returns the next object or 0 if 'obj' is the last object. |
648 |
|
649 |
GetObjectAt(map map, int x, int y) |
650 |
Get the first object at position (x,y) in the map. |
651 |
Returns the object or 0 if the position is empty. |
652 |
|
653 |
GetObjectCost(object who, object obj, int type) |
654 |
Determine the cost of an object 'obj' if 'who' would buy or sell it. The |
655 |
parameter 'type' should be one or more values returned by CostFlagXxx(). |
656 |
Returns the cost in silver coins as an integer. |
657 |
|
658 |
GetObjectMoney(object who) |
659 |
Determine how much money 'who' is carrying, including what is in containers. |
660 |
Returns the amount in silver coins as an integer. |
661 |
|
662 |
GetPlayerDirectory() |
663 |
Return the name of the base directory containing the Crossfire players files. |
664 |
You need to concatenate the result with the value returned by |
665 |
GetLocalDirectory() to get an absolute path. |
666 |
Returns the directory as a string. |
667 |
|
668 |
GetPower(object who) |
669 |
Get the Power value of the given object. |
670 |
Returns the power value as an integer. |
671 |
|
672 |
GetPressure(int x, int y, map map) |
673 |
Get the humidity level of a given square of a map. |
674 |
Returns the humidity level as an integer. |
675 |
|
676 |
Remark: not implemented. Always returns zero. |
677 |
|
678 |
GetPreviousObject(object obj) |
679 |
Get the object before 'obj'. |
680 |
Returns the previous object or 0 if 'obj' is the first object. |
681 |
|
682 |
GetQuantity(object obj) |
683 |
Return the number of items this object represents. |
684 |
Returns the number as a long. |
685 |
|
686 |
GetReturnValue() |
687 |
Return the current exit status of the event script as an integer. See below |
688 |
for an overview of events that use the exit value. |
689 |
|
690 |
GetSkillExperience(object who, string skill) |
691 |
Get the experience of skill 'skill' the object 'who' has. 'skill' should |
692 |
skill name. |
693 |
Returns the skill experience as a long or no value if 'who' does not know the |
694 |
skill. |
695 |
Example: |
696 |
who = CFPython.WhoIsActivator() |
697 |
exp = CFPython.GetSkillExperience(who, "alchemy") |
698 |
if exp != None: |
699 |
CFPython.Write("Alchemy experience %d"%(exp), who) |
700 |
else: |
701 |
CFPython.Write("Alchemy skill is unknown", who) |
702 |
|
703 |
GetSlaying(object obj) |
704 |
Get the "slaying" field of an object. |
705 |
Returns the slaying value as a string. |
706 |
|
707 |
GetSP(object who) |
708 |
Get the amount of mana possessed by the given object. |
709 |
Returns the amount of mana as an integer. |
710 |
|
711 |
GetSpeed(object who) |
712 |
Get the speed of the given object. |
713 |
Returns the speed as a float. |
714 |
|
715 |
GetStrength(object who) |
716 |
Get the Strength value of the given object. |
717 |
Returns the strength as an integer. |
718 |
|
719 |
GetTempDirectory() |
720 |
Return the name of the base directory containing temporary Crossfire files |
721 |
(for example swapped-out maps). |
722 |
Returns the directory as a string. |
723 |
|
724 |
GetTemperature(int x, int y, map map) |
725 |
Get the temperature of a given square of a map. |
726 |
Returns the temperature as an integer. |
727 |
|
728 |
Remark: not implemented. Always returns zero. |
729 |
|
730 |
GetTitle(object who) |
731 |
Get the title of 'who'. The "title" is the artifact suffix of in item. For |
732 |
example, an "gauntlets of the Titans" has the title "of the Titans". |
733 |
Returns the title as a string or no value if the object has no title. |
734 |
|
735 |
Note: this function does not return the title the player has chosen for |
736 |
himself. |
737 |
|
738 |
GetType(object who) |
739 |
Get the type of a given object, as a numerical identifier. |
740 |
Returns the type as an integer. |
741 |
|
742 |
GetUniqueDirectory() |
743 |
Return the name of the base directory containing the Crossfire Unique items. |
744 |
You need to concatenate the result with the value returned by |
745 |
GetLocalDirectory() to get an absolute path. |
746 |
Returns the directory as a string. |
747 |
|
748 |
GetValue(object who) |
749 |
Get the "value" field of an object. |
750 |
Returns the value as an integer. |
751 |
|
752 |
GetWC(object who) |
753 |
Get the Weapon Class coefficient associated with the given object. |
754 |
Returns the weapon class coefficient as an integer. |
755 |
|
756 |
GetWeight(object who) |
757 |
Determine the weight of the given object. The weight does not include the |
758 |
inventory. |
759 |
Returns the weight in grams as an integer. |
760 |
|
761 |
GetWisdom(object who) |
762 |
Get the Wisdom value of the given object. |
763 |
Returns the wisdom value as an integer. |
764 |
|
765 |
GetXPosition(object obj) |
766 |
Get the x-position of an object in its map. |
767 |
Returns the x-position as an integer. |
768 |
|
769 |
GetYPosition() |
770 |
Get the y-position of an object in its map. |
771 |
Returns the y-position as an integer. |
772 |
|
773 |
H |
774 |
HasBeenApplied(object obj) |
775 |
Check whether the object has been applied before. |
776 |
Return value: test result as an integer - 0 if and only if false. |
777 |
|
778 |
HasStealth(object obj) |
779 |
Check whether the object is stealthy. |
780 |
Return value: test result as an integer - 0 if and only if false. |
781 |
|
782 |
HasXRays() |
783 |
Check whether the object uses or grants x-rays. |
784 |
Return value: test result as an integer - 0 if and only if false. |
785 |
|
786 |
HitBack() |
787 |
Check whether the object has the hitback flag set. |
788 |
Return value: test result as an integer - 0 if and only if false. |
789 |
|
790 |
I |
791 |
InsertObjectInside(object obj, object environment) |
792 |
Insert the object 'obj' into 'environment'. |
793 |
Does not return a value. |
794 |
|
795 |
Example: see SetSlaying() |
796 |
|
797 |
IsAlive(object who) |
798 |
Test if the given object is alive. |
799 |
Return value: test result as an integer - 0 if and only if false. |
800 |
|
801 |
IsApplied(object who) |
802 |
Test if the given object is applied. |
803 |
Return value: test result as an integer - 0 if and only if false. |
804 |
|
805 |
IsBlind(object who) |
806 |
Test if the given object causes blindness. For players, tests if he is blind. |
807 |
Return value: test result as an integer - 0 if and only if false. |
808 |
|
809 |
IsCanBePicked(object who) |
810 |
Test if on object can be picked up. |
811 |
Return value: test result as an integer - 0 if and only if false. |
812 |
|
813 |
IsConfused(object who) |
814 |
Test if the given object is confused. |
815 |
Return value: test result as an integer - 0 if and only if false. |
816 |
|
817 |
IsCursed(object who) |
818 |
Test if the given object is cursed. Not that not all "damned" objects are |
819 |
cursed as well. |
820 |
Return value: test result as an integer - 0 if and only if false. |
821 |
|
822 |
IsDamned(object who) |
823 |
Test if the given object is damned. |
824 |
Return value: test result as an integer - 0 if and only if false. |
825 |
|
826 |
IsDungeonMaster(object who) |
827 |
Test if the given object is a DM. |
828 |
Return value: test result as an integer - 0 if and only if false. |
829 |
|
830 |
IsFloor(object who) |
831 |
Test if the given object is a floor tile. |
832 |
Return value: test result as an integer - 0 if and only if false. |
833 |
|
834 |
IsFlying(object who) |
835 |
Test if the given object is flying. |
836 |
Return value: test result as an integer - 0 if and only if false. |
837 |
|
838 |
IsFriendly(object who) |
839 |
Test if the given object is in friendly mode. |
840 |
Return value: test result as an integer - 0 if and only if false. |
841 |
|
842 |
IsGenerator(object who) |
843 |
Test if the given object is a generator. |
844 |
Return value: test result as an integer - 0 if and only if false. |
845 |
|
846 |
IsIdentified(object who) |
847 |
Test if the given object is identified. |
848 |
Return value: test result as an integer - 0 if and only if false. |
849 |
|
850 |
IsInvisible(object who) |
851 |
Test if the given object is invisible. |
852 |
Return value: test result as an integer - 0 if and only if false. |
853 |
|
854 |
IsKnownCursed(object who) |
855 |
Test if the given object is known to be a cursed one. |
856 |
Return value: test result as an integer - 0 if and only if false. |
857 |
|
858 |
IsKnownMagical(object who) |
859 |
Test if the given object is known to be a magical one. |
860 |
Return value: test result as an integer - 0 if and only if false. |
861 |
|
862 |
IsLifesaver(object who) |
863 |
Test if the given object is a Lifesaver. For players, tests if he wears an |
864 |
object that is a Lifesaver. |
865 |
Return value: test result as an integer - 0 if and only if false. |
866 |
|
867 |
IsMonster(object who) |
868 |
Test if the given object is a monster. |
869 |
Return value: test result as an integer - 0 if and only if false. |
870 |
|
871 |
IsOfType(object obj, int type) |
872 |
Check if the object is of the given type. |
873 |
Return value: test result as an integer - 0 if and only if false. |
874 |
|
875 |
Note: There is no function to determine the type values by name. |
876 |
|
877 |
Example: |
878 |
if CFPython.IsOfType(CFPython.CreateObject("ring", (0, 0)), 70): # 70=RING |
879 |
# item is a ring |
880 |
|
881 |
IsOutOfMap(object obj, int x, int y) |
882 |
Check if the object would be outside of the current map if moved to (x,y). |
883 |
This function works for tiled maps. |
884 |
Return value: test result as an integer - 0 if and only if false. |
885 |
|
886 |
IsRunningAway(object who) |
887 |
Test if the given object is running away. |
888 |
Return value: test result as an integer - 0 if and only if false. |
889 |
|
890 |
IsScared(object who) |
891 |
Test if the given object is scared. |
892 |
Return value: test result as an integer - 0 if and only if false. |
893 |
|
894 |
IsSleeping(object who) |
895 |
Test if the given object is sleeping. |
896 |
Return value: test result as an integer - 0 if and only if false. |
897 |
|
898 |
IsSplitting(object who) |
899 |
Test if the given object can split. |
900 |
Return value: test result as an integer - 0 if and only if false. |
901 |
|
902 |
IsThrown(object who) |
903 |
Test if the given object is designed to be thrown. |
904 |
Return value: test result as an integer - 0 if and only if false. |
905 |
|
906 |
IsTurnable(object who) |
907 |
Test if the given object can change its face with direction. |
908 |
Return value: test result as an integer - 0 if and only if false. |
909 |
|
910 |
Note: use SetDirection(who) to change the direction of turnable objects. |
911 |
|
912 |
IsUnaggressive(object who) |
913 |
Test if the given object is in unaggressive mode. |
914 |
Return value: test result as an integer - 0 if and only if false. |
915 |
|
916 |
IsUndead(object who) |
917 |
Test if the given object is an undead. |
918 |
Return value: test result as an integer - 0 if and only if false. |
919 |
|
920 |
IsUnique(object who) |
921 |
Test if the given object is unique. |
922 |
Return value: test result as an integer - 0 if and only if false. |
923 |
|
924 |
IsUnpaid(object who) |
925 |
Test if the given object is paid. |
926 |
Return value: test result as an integer - 0 if and only if false. |
927 |
|
928 |
IsUsedUp(object who) |
929 |
Test if the given object has the flag "FLAG_IS_USED_UP" set. |
930 |
Return value: test result as an integer - 0 if and only if false. |
931 |
|
932 |
Example: |
933 |
who = CFPython.WhoIsActivator() |
934 |
obj = CFPython.CreateObject("burning item", (0, 0)) |
935 |
CFPython.Write("IsUsedUp(%s)=%d"%(CFPython.GetName(obj), CFPython.IsUsedUp(obj)), who) |
936 |
|
937 |
|
938 |
J |
939 |
K |
940 |
KillObject(object who, object what, int type) |
941 |
Kill the object 'what' in an combat-like fashion. 'who' is the object killing |
942 |
'what'. 'type' is the attack type; it should be one or more values returned |
943 |
by AttackTypeXxx(). |
944 |
Does not return a value. |
945 |
|
946 |
Note: the death event of 'what' will be called. |
947 |
|
948 |
L |
949 |
LoadObject(string str) |
950 |
Construct an object from its string representation. Use SaveObject() to |
951 |
convert an object into its string representation. |
952 |
Returns the created object or 0 if the object could no be created. |
953 |
|
954 |
M |
955 |
MakeInvisible(object obj) |
956 |
Test if the given object makes the wielder invisible. For players, tests if |
957 |
he is invisible. |
958 |
Return value: test result as an integer - 0 if and only if false. |
959 |
|
960 |
MatchString(string str, string regex) |
961 |
Try to match the string 'str' to a regular expression 'regex'. |
962 |
Return value: test result as an integer - 0 if and only if false. |
963 |
|
964 |
Message(string text, object who[, int color]) |
965 |
Write the message 'text' to the map of 'who'. 'color' determines the color |
966 |
and flags to use. (Consult the crossfire source code for all available flags |
967 |
NDI_*.) If 'color' if omitted, NDI_BLUE|NDI_UNIQUE is used. |
968 |
Does not return a value. |
969 |
|
970 |
Note: to write a message to just one player, use Write(). |
971 |
|
972 |
N |
973 |
O |
974 |
OnlyAttack(object who) |
975 |
Test if the given object evaporates if it has no enemy. |
976 |
Return value: test result as an integer - 0 if and only if false. |
977 |
|
978 |
P |
979 |
PayAmount(object buyer, int silver) |
980 |
Remove a given amount of silver coins from the buyer object. It uses money |
981 |
from the inventory or from pouches in the inventory of 'buyer'. |
982 |
Returns an integer, 1 for success or 0 for failure. |
983 |
|
984 |
PayForItem(object buyer, object what) |
985 |
Make 'buyer' to buy the object 'what'. Removes the necessary money from the |
986 |
inventory or from pouches in the inventory. It grants bargaining experience |
987 |
for a successful completion. |
988 |
Returns an integer, 1 for success or 0 for failure. |
989 |
|
990 |
PickUp(object who, object what) |
991 |
Make 'who' pick up the object 'what'. |
992 |
Does not return a value. |
993 |
|
994 |
Q |
995 |
R |
996 |
ReadyMap(string mapname) |
997 |
Return the map with the name 'mapname'. The functions loads (or swaps in) the |
998 |
map if necessary. |
999 |
Returns the map or 0 if the map could not be loaded. |
1000 |
|
1001 |
Example: |
1002 |
# teleport activator to another map |
1003 |
map = CFPython.ReadyMap("/scorn/misc/beginners") |
1004 |
CFPython.Teleport(CFPython.WhoIsActivator(), map, 10, 10) |
1005 |
|
1006 |
ReflectMissiles(object obj) |
1007 |
Test if the given object reflects missiles. For players, tests if he reflects |
1008 |
missiles. |
1009 |
Return value: test result as an integer - 0 if and only if false. |
1010 |
|
1011 |
ReflectSpells(object obj) |
1012 |
Test if the given object reflects spells. For players, tests if he reflects |
1013 |
spells. |
1014 |
Return value: test result as an integer - 0 if and only if false. |
1015 |
|
1016 |
RegisterCommand(string command, string script, float speed) |
1017 |
Define a new command that players can call. 'script' is the Python script to |
1018 |
execute if a player issues 'command'. 'speed' determines how long the command |
1019 |
will paralyze the player. |
1020 |
|
1021 |
When the script is run, WhoAmI() will return the player that issued the |
1022 |
command. WhatIsMessage() returns the command parameters (if any). |
1023 |
Throws an exception if the command is already registered or if 'speed' is |
1024 |
negative. |
1025 |
If the script fails, it should call SetReturnValue(0). |
1026 |
|
1027 |
Note: It is possible to overwrite internal commands. |
1028 |
|
1029 |
RemoveObject(object obj) |
1030 |
Remove an object from its environment (and frees it). |
1031 |
Does not return a value. |
1032 |
|
1033 |
Note: do not use the object 'obj' afterwards. |
1034 |
|
1035 |
Note: if the removed object is a container, the objects inside are not freed, |
1036 |
they are dropped to the ground. |
1037 |
|
1038 |
S |
1039 |
|
1040 |
|
1041 |
SendCustomCommand(object player, string cmd) |
1042 |
Send 'cmd' to the crossfire client of 'player'. Consult the crossfire |
1043 |
protocol specification for valid commands. 'player' must be a player object. |
1044 |
Does not return a value. |
1045 |
|
1046 |
Example: |
1047 |
CFPython.SendCustomCommand(CFPython.WhoIsActivator(), "drawinfo 1 text") |
1048 |
|
1049 |
SetAC(object obj, int value) |
1050 |
Set the Armor Class coefficient if the given object to 'value'. |
1051 |
Does not return a value. |
1052 |
Throws an exception if the value is less than -120 or higher than 120. |
1053 |
|
1054 |
SetAttackType(object obj, int type) |
1055 |
Sets the attack type of an object. The type can be one or more return values |
1056 |
of AttackTypeXxx(). |
1057 |
Does not return a value. |
1058 |
|
1059 |
Example: |
1060 |
# create a sword with fire and cold attack type |
1061 |
sword = CFPython.CreateObject("sword", (1, 3)) |
1062 |
CFPython.SetAttackType(sword, CFPython.AttackTypeFire()|CFPython.AttackTypeCold()) |
1063 |
CFPython.SetIdentified(sword, 1) |
1064 |
|
1065 |
SetBeenApplied(object obj, int flag) |
1066 |
Mark the object as been applied before (flag != 0) or has never been applied |
1067 |
(flag = 0). |
1068 |
Does not return a value. |
1069 |
|
1070 |
SetCharisma(object obj, int value) |
1071 |
Set the Charisma value of the given object. |
1072 |
Does not return a value. |
1073 |
Throws an exception if the value is less than -30 or higher than 30. |
1074 |
|
1075 |
SetConstitution(object obj, int value) |
1076 |
Set the Constitution value of the given object. |
1077 |
Does not return a value. |
1078 |
Throws an exception if the value is less than -30 or higher than 30. |
1079 |
|
1080 |
SetCursed(object obj, int flag) |
1081 |
Make the object cursed (flag != 0) or removes a curse (flag = 0). |
1082 |
Does not return a value. |
1083 |
|
1084 |
Note: does not remove the damned flag - use SetDamned() to change the damned |
1085 |
status. |
1086 |
|
1087 |
SetDamage(object obj, int value) |
1088 |
Set the amount of damage associated with the given object. |
1089 |
Does not return a value. |
1090 |
Throws an exception if the value is negative or higher than 120. |
1091 |
|
1092 |
SetDamned(object obj, int flag) |
1093 |
Make the object damned (flag != 0) or removes a damnation (flag = 0). |
1094 |
Does not return a value. |
1095 |
|
1096 |
Note: does not affect the cursed flag - use SetCursed() to change the cursed |
1097 |
status. |
1098 |
|
1099 |
SetDexterity(object obj, int value) |
1100 |
Set the Dexterity value of the given object. |
1101 |
Does not return a value. |
1102 |
Throws an exception if the value is less than -30 or higher than 30. |
1103 |
|
1104 |
SetDirection(object who, int dir) |
1105 |
Set the direction 'who' is currently moving. |
1106 |
Does not return a value. |
1107 |
|
1108 |
SetFace(object obj, string anim) |
1109 |
Set the face of an object 'obj' to 'anim'. 'anim' is an animation name. |
1110 |
Does not return a value. |
1111 |
|
1112 |
Example: |
1113 |
# make a pair of speed boots look like Idaten boots |
1114 |
obj = CFPython.CreateObject("speedboots", (1, 3)) |
1115 |
CFPython.SetFace(obj, "idaten") |
1116 |
|
1117 |
SetFood(object who, int food) |
1118 |
Set the food level of the given object. |
1119 |
Does not return a value. |
1120 |
Throws an exception if the value is negative or higher than 999. |
1121 |
|
1122 |
SetGod(object who, string god) |
1123 |
Make 'who' to become a follower of 'god'. |
1124 |
Does not return a value. |
1125 |
Throws an exception if 'god' is invalid. |
1126 |
|
1127 |
Note: Does nothing if 'who' does not know the skill 'praying'. |
1128 |
|
1129 |
SetGrace(object obj, int value) |
1130 |
Set the grace amount of the given object. |
1131 |
Does not return a value. |
1132 |
Throws an exception if the value is less than -32000 or higher than 32000. |
1133 |
|
1134 |
SetHP(object obj, int value) |
1135 |
Set the amount of Hit Points associated with the given object. |
1136 |
Does not return a value. |
1137 |
Throws an exception if the value is negative or higher than 32000. |
1138 |
|
1139 |
SetIdentified(object obj, int flag) |
1140 |
Mark the object as identified (flag != 0) or not identified (flag = 0). |
1141 |
Does not return a value. |
1142 |
|
1143 |
SetIntelligence(object who, int value) |
1144 |
Set the Intelligence value of the given object. |
1145 |
Does not return a value. |
1146 |
Throws an exception if the value is less than -30 or higher than 30. |
1147 |
|
1148 |
SetInvisible(object obj, int flag) |
1149 |
Set (flag != 0) or clears (flag = 0) the invisible flag of the object. |
1150 |
Does not return a value. |
1151 |
|
1152 |
SetLastGrace(object who, int value) |
1153 |
Set the last_grace parameter value associated with the given object. |
1154 |
Does not return a value. |
1155 |
Throws an exception if the value is negative or higher than 32000. |
1156 |
|
1157 |
SetLastSP(object who, int value) |
1158 |
Set the last_sp parameter value associated with the given object. |
1159 |
Does not return a value. |
1160 |
Throws an exception if the value is negative or higher than 32000. |
1161 |
|
1162 |
SetMaxHP(object who, int value) |
1163 |
Set the maximum amount of Hit Points the given object can get. |
1164 |
Does not return a value. |
1165 |
Throws an exception if the value is negative or higher than 32000. |
1166 |
|
1167 |
SetMaxSP(object who, int value) |
1168 |
Set the maximum amount of mana the given object can get. |
1169 |
Does not return a value. |
1170 |
Throws an exception if the value is negative or higher than 32000. |
1171 |
|
1172 |
SetMessage(object obj, string msg) |
1173 |
Set the message contained in the specified object. The message is what |
1174 |
appears inside msg...endmsg tags. |
1175 |
Does not return a value. |
1176 |
|
1177 |
SetName(object name, string name[, string name_pl]) |
1178 |
Set the 'clear name' of the given object. If 'name_pl' (name to use for |
1179 |
multiple objects) is not given, 'name' is used. |
1180 |
Does not return a value. |
1181 |
|
1182 |
Example: |
1183 |
# create a scroll with a custom name |
1184 |
key = CFPython.CreateObject("scroll", (0, 0)) |
1185 |
CFPython.SetName(key, "warning scroll", "warning scrolls") |
1186 |
CFPython.SetMessage(key, "<unreadable text>") |
1187 |
|
1188 |
SetNickname(object obj, string name) |
1189 |
Set the title of a player or an object. |
1190 |
Does not return a value. |
1191 |
|
1192 |
SetPosition(object obj, (int x, int y)) |
1193 |
Move an object to another spot on the same map. The object must not be part |
1194 |
of an inventory. Places the item in a nearby spot if the destination spot is |
1195 |
blocked. The object will no be moved if no free spot can be found. |
1196 |
Does not return a value. |
1197 |
|
1198 |
SetPower(object obj, int value) |
1199 |
Set the Power value of the given object. |
1200 |
Does not return a value. |
1201 |
Throws an exception if the value is less than -30 or higher than 30. |
1202 |
|
1203 |
SetQuantity(object obj, int nrof) |
1204 |
Set the number of items this object represents. |
1205 |
Does not return a value. |
1206 |
Throws an exception if the value is negative. |
1207 |
|
1208 |
Note: the object should not be in a player's inventory because the client |
1209 |
view will not be updated. |
1210 |
|
1211 |
Note: "nrof=0" does not mean "destroy the item". |
1212 |
|
1213 |
SetReturnValue(int value) |
1214 |
Set the current exit status of the event script. See below for an overview of |
1215 |
events that use the exit value. |
1216 |
Does not return a value. |
1217 |
|
1218 |
SetSkillExperience(object who, string skill, long exp) |
1219 |
Set the experience of skill 'skill' the object 'who' has. 'skill' should be a |
1220 |
skill name. |
1221 |
Does not return a value. |
1222 |
Throws an exception if 'who' does not know the 'skill'. |
1223 |
Throws an exception if the value is negative. |
1224 |
|
1225 |
Note: If the new experience value is less than the current value, 'who' |
1226 |
looses the difference from his total experience. |
1227 |
|
1228 |
SetSlaying(object obj, string value) |
1229 |
Set the "slaying" field of an object. |
1230 |
Does not return a value. |
1231 |
|
1232 |
Example: |
1233 |
# create a key and set its lock-code |
1234 |
key = CFPython.CreateObject("key2", (0, 0)) |
1235 |
CFPython.SetName(key, "treasure key") |
1236 |
CFPython.SetSlaying(key, "treasure-code") |
1237 |
CFPython.InsertObjectInside(key, CFPython.WhoIsActivator()) |
1238 |
|
1239 |
SetSP(object obj, int value) |
1240 |
Set the amount of mana possessed by the given object. |
1241 |
Does not return a value. |
1242 |
Throws an exception if the value is negative or higher than 32000. |
1243 |
|
1244 |
SetSpeed(object obj, float value) |
1245 |
Set the speed value of the given object. |
1246 |
Does not return a value. |
1247 |
Throws an exception if the speed value is less than -9.99 or higher than |
1248 |
9.99. |
1249 |
|
1250 |
SetStrength(object obj, int value) |
1251 |
Set the Strength value of the given object. |
1252 |
Does not return a value. |
1253 |
Throws an exception if the value is less than -30 or higher than 30. |
1254 |
|
1255 |
SetTitle(object obj, string title) |
1256 |
Set the title of the given object. |
1257 |
Note: to set the title of a player, use SetNickname() instead. |
1258 |
Does not return a value. |
1259 |
|
1260 |
SetUnaggressive(object obj, int flag) |
1261 |
Make the given object unaggressive (flag != 0) or aggressive (flag = 0). |
1262 |
Does not return a value. |
1263 |
|
1264 |
SetValue(object obj, int silver) |
1265 |
Set the "value" field of an object in silver coins. |
1266 |
Does not return a value. |
1267 |
Throws an exception if the value is negative. |
1268 |
|
1269 |
SetVariable(object obj, string value) |
1270 |
Change an object according to an argument string. It is equivalent of the DM |
1271 |
patch command. |
1272 |
Does not return a value. |
1273 |
|
1274 |
SetWC(object obj. int value) |
1275 |
Set the Weapon Class coefficient associated with the given object. |
1276 |
Does not return a value. |
1277 |
Throws an exception if the value is less than -120 or higher than 120. |
1278 |
|
1279 |
SetWeight(object obj, long weight) |
1280 |
Set the weight (in grams) of the given object. |
1281 |
Does not return a value. |
1282 |
Throws an exception if the value is negative or higher than 1000000000. |
1283 |
|
1284 |
SetWisdom(object obj, int value) |
1285 |
Set the Wisdom value of the given object. |
1286 |
Does not return a value. |
1287 |
Throws an exception if the value is less than -30 or higher than 30. |
1288 |
|
1289 |
StandStill(object obj) |
1290 |
Test if the given object has the flag "FLAG_STAND_STILL" set. |
1291 |
Return value: test result as an integer - 0 if and only if false. |
1292 |
|
1293 |
T |
1294 |
Take(object who, string what) |
1295 |
Make 'who' to pick up 'what'. The syntax of 'what' is the same as what is |
1296 |
allowed for the client command 'get'. |
1297 |
Does not return a value. |
1298 |
|
1299 |
Teleport(object who, map map, int x, int y) |
1300 |
Move the given object to (x,y) in map 'map'. The object to be moved may be |
1301 |
part of a map or in some object's inventory. If the destination position is |
1302 |
blocked, the object is placed in a nearby space. |
1303 |
Does not return a value. |
1304 |
|
1305 |
Note: if the destination coordinates are outside of the map or if no free |
1306 |
space could be found, this function does not move the object. |
1307 |
|
1308 |
Note: the object to be moved should not be part of a player's inventory. |
1309 |
|
1310 |
U |
1311 |
V |
1312 |
W |
1313 |
WasDungeonMaster(object who) |
1314 |
Test if the given object is or has been a DM. |
1315 |
Return value: test result as an integer - 0 if and only if false. |
1316 |
|
1317 |
WhatIsMessage() |
1318 |
Return the message related to the current event as a string or no object if |
1319 |
no message is applicable. |
1320 |
|
1321 |
Note: see below for an overview of events with messages. |
1322 |
|
1323 |
WhoAmI() |
1324 |
Return the object related to the current event or 0 if not applicable. |
1325 |
|
1326 |
Note: the related object is frequently (but not always) the object containing |
1327 |
the script. See below for an overview of events with related objects. |
1328 |
|
1329 |
WhoIsActivator() |
1330 |
Return the object that caused the script to run or 0 if not applicable. |
1331 |
Note: See below for an overview of events with activator objects. |
1332 |
|
1333 |
WhoIsOther() |
1334 |
Return an auxiliary object for the current event or 0 if not applicable. |
1335 |
|
1336 |
Note: See below for an overview of events with auxiliary objects. |
1337 |
|
1338 |
Write(string text, object who[, int color]) |
1339 |
Write the message 'text' to the player 'who'. 'color' determines the color |
1340 |
and flags to use. (Consult the crossfire source code for all available flags |
1341 |
NDI_*.) If 'color' if omitted, NDI_BLUE|NDI_UNIQUE is used. |
1342 |
Does not return a value. |
1343 |
|
1344 |
Note: to write a message to all players in a map, use Message(). |
1345 |
|
1346 |
X |
1347 |
Y |
1348 |
Z |
1349 |
|
1350 |
|
1351 |
What parameters are available to a script? |
1352 |
------------------------------------------ |
1353 |
|
1354 |
The following table contains all events that can be tied to objects. |
1355 |
|
1356 |
event Activator WhoAmI Other Message parm1 parm2 parm3 result comment |
1357 |
----- --------- ------ ----- ------- ----- ----- ----- ------ -------------- |
1358 |
apply op ALTAR - - 0 0 0 yes 'op' prays at 'altar' |
1359 |
apply op BOOK - - 0 0 0 no 'op' reads 'book' |
1360 |
apply op ITEM - - aflag 0 0 yes 'op' applies 'item' |
1361 |
attack hitter hitter OP - 0 dam wc no 'hitter' hits 'op' |
1362 |
attack hitter ITEM op - 0 dam wc no 'hitter' hits 'op' with 'item' |
1363 |
close op CONTAINER - - 0 0 0 yes 'op' closes 'container' |
1364 |
death - PLAYER - - 0 0 0 yes 'player' dies |
1365 |
death hitter OP - - atype 0 0 yes 'hitter' kills 'op' |
1366 |
drop op ITEM - - nrof 0 0 yes 'op' drops 'item' |
1367 |
pickup (not implemented) |
1368 |
say op ITEM npc msg 0 0 0 always 'op' tells 'msg' to 'item' in 'npc''s inventory |
1369 |
say op NPC - msg 0 0 0 always 'op' tells 'msg' to 'npc' |
1370 |
stop - OP - - 0 0 0 no thrown object 'op' is stopped |
1371 |
throw op ITEM - - 0 0 0 no 'op' throws 'item' |
1372 |
time - OP - - 0 0 0 no 'op' takes a turn |
1373 |
timer OP - - - 0 0 0 no timer of 'op' has expired |
1374 |
trigger OP item - msg 0 0 0 always 'op' writes 'msg' into 'item' |
1375 |
trigger TELEPORTER op - - 0 0 0 yes 'teleporter' moves 'op' |
1376 |
trigger TRAP originator victim - 0 0 0 yes 'originator' causes 'victim' to trigger 'trap' |
1377 |
|
1378 |
Notes: |
1379 |
- the object that contains the event script is written in capitals. |
1380 |
- result column: indicates how the result value set by SetReturnValue() is |
1381 |
used: no=result value is not used; yes=non-zero result value prevents the |
1382 |
normal action; always=prevents the normal action regardless of result value. |
1383 |
- apply event: aflag: Consult the crossfire source code for all available flags |
1384 |
AP_*. |
1385 |
- death event: atype=attacktype |
1386 |
- trigger event: originator is unset if the trap (pedestal/button) someone left |
1387 |
it. |
1388 |
- parm1..3 are not currently available to the script. |
1389 |
- attack event: 'item' can be a weapon or a missile. |
1390 |
|
1391 |
|
1392 |
The following table contains all global events. |
1393 |
|
1394 |
event Activator WhoAmI Other Message comment |
1395 |
----- --------- ------ ----- -------- -------------- |
1396 |
born op - - - new player 'op' was created |
1397 |
clock - - - - called each tick |
1398 |
crash (not implemented) |
1399 |
gdeath player 'op' dies (not implemented) |
1400 |
gkill 'hitter' kills 'op' (not implemented) |
1401 |
kick op - - name player 'op' named 'name' is kicked out of the game |
1402 |
login op op - ip player 'op' logged in from IP address 'ip' |
1403 |
logout op op - ip player 'op' logged out from IP address 'ip' |
1404 |
mapenter op - - - player 'op' has entered a new map |
1405 |
mapleave op - - - player 'op' is leaving a map |
1406 |
mapreset - - - mappath map 'mappath' is resetting |
1407 |
muzzle op - - name player 'op' named 'name' is muzzled |
1408 |
remove op - - - player 'op' quits the game |
1409 |
shout op - - message player 'op' shouts 'message' |
1410 |
tell (not implemented) |
1411 |
|
1412 |
Notes: |
1413 |
- kick event: param is either the player name or None if all players are |
1414 |
kicked. |
1415 |
- login event: this event is also called when a new player was created. |