[Crossfire-wiki] [Crossfire DokuWiki] page changed: cfpython
no-reply_wiki at metalforge.org
no-reply_wiki at metalforge.org
Sat Apr 28 14:03:37 CDT 2007
A page in your DokuWiki was added or changed. Here are the details:
Date : 2007/04/28 14:03
User : ryo
Edit Summary: document functions, and such
@@ -1,9 +1,14 @@
Python plugin is a [[server plugin]] able to run Python scripts that manipulate Crossfire items, monsters, players, maps, ...
The latest version, 2.0, is a major rewrite which introduces Python objects to represent maps, Crossfire objects and players. The hooking system also changed.
- Old plugin's reference can be found on [[plugin_python]].
+ Note that this guide doesn't intend to teach you Python. Documentation for that is available on [[http://docs.python.org|Python's official web site]].
+
+ Also, advanced functions can require some knowledge of Crossfire's inner workings. Developers seeking help should check [[http://crossfire.real-time.com/resources/index.html|Crossfire's resource page]]. Another option is to check existing Python scripts, available in the [[http://crossfire.svn.sourceforge.net/viewvc/crossfire/maps/trunk/python/|maps source tree]].
+
+
+ Old plugin's reference can be found on [[plugin_python]], for historical purposes.
**Important note:** the API, and other parts, are valid for code's ''trunk''. ''branch'' contains hopefully all the changes too, but there may be differences. Also, links to SVN are to trunk.
====== General information ======
@@ -56,9 +61,13 @@
* ''EventType'': EVENT_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/plugin.h?view=markup|include/plugin.h]]''
* ''MessageFlag'': NDI_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/newclient.h?view=markup|include/newclient.h]]''
* ''Move'': movement types, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/define.h?view=markup|include/define.h]]''
* ''Type'': object type, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/define.h?view=markup|include/define.h]]''
+
+ ''MessageFlag'' and ''Move'' can be combined, using +, to build multiple values.
+
{FIXME} do a nice table, with link to values?
+
Example:
<code>
whoami.Say("%s => %d"%(Crossfire.DirectionName[Crossfire.Direction.NORTH], Crossfire.Direction.NORTH))
</code>
@@ -152,17 +161,21 @@
Returns the ''[[cfpython#crossfire.map_methods_and_attributes|Crossfire.Map]]'' with specified path, or ''None'' if such a map isn't loaded. Will not try to load the map, see ''[[cfpython#readymap|Crossfire.ReadyMap]]'' for that.
==== Action functions ====
Those functions enable the script to manipulate runtime objects.
+
=== ReadyMap ===
- Parameter:
- * map name (''String'')
- * optional: flags (''Number'')
Loads specified map, and returns a ''Crossfire.Map'' object wrapping it. Will return ''None'' if map couldn't be found.
- ''Flags'' specifies what kind of map should be loaded. It matches the 2nd argument of ''ready_map_name()'' {FIXME} add flags and such
+ Parameter:
+ * ''String'', the map path to load
+ * ''Number'', flags, optional. Combination of the following values:
+ * 2: map is a player's unique map. Path is assumed to be the full path already, and it won't be changed
+ * 16: map is reloaded anyway, even if it is already loaded
+
=== CreateObject ===
Returns an empty object which can then be manipulated and inserted in a map.
+
=== CreateObjectByName ===
Parameters:
* object or archetype name (''String'')
@@ -225,21 +238,23 @@
Returns ''1'' if string matches the pattern, ''0'' else.
Pattern can be a regular expression FIXME specifications
+
===== Crossfire.Archetype methods and attributes =====
This represents an archetype, from which all objects are derived.
Pointer to such item can be obtained through the ''Crossfire.Object.Archetype'' or the list returned by ''Crossfire.GetArchetypes()''.
Properties:
- * Clone: returns a ''Crossfire.Object'' representing the default values for items of that archetype. Will never be ''None''
+ * Clone: returns a ''Crossfire.Object'' representing the default values for items of that archetype. Will never be ''None''. Its values can't be changed (but trying to change one will not result in any error)
* Head: archetype to which this archetype is linked to. Will be ''None'' if not applicable
* Name: archetype's name
* Next: next archetype in the archetype list. Will be ''None'' for last item
* More: next archetype linked to current archetype. Will be ''None'' for last item
Methods:
- * NewObject: returns a ''Crossfire.Object'' having this archetype as type
+ * NewObject: returns a ''Crossfire.Object'' having this archetype as type. It isn't on any map or in any inventory, so should be inserted somewhere or deleted if not used.
+
===== Crossfire.Object methods and attributes =====
FIXME link to dev:objects 's fields? split flag & such info. Make a table with property / mapping to object / Python type
Properties in **bold** are read-write, others are readonly. Most properties are mapped to fields of the ''object'' structure. ''Boolean'' values are mapped to the various flags.
* **Name**: ''String'' containing the object's name
@@ -360,15 +375,18 @@
* Count
* **GodGiven**: ''Boolean''
* **IsPet**: if the object is on the friendly list or not
* **AttackMovement**
+
==== Methods ====
FIXME document all parameters. Link to relevant Crossfire function. Split in "standard function" and "helper function"?
+
=== ActivateRune ===
Current object springs like a trap, hitting the victim.
Arguments:
* ''Crossfire.Object'' that is the victim of the trap.
+
=== AddExp ===
Adds or substracts experience to current object.
Arguments:
@@ -378,8 +396,9 @@
* 0: give the player the skill
* 1: give player exp to total, no skill
* 2: player gets nothing
* 3: used when removing exp
+
=== AddTimer ===
Fires an ''event_timer'' after the specified delay. Object should have a handler for this event.
Arguments:
@@ -388,8 +407,9 @@
* 1: delay is in seconds
* 2: delay is in server cycles
Returns: timer identifier, which can be used to remove the timer through a call to ''[[cfpython#DestroyTimer|Crossfire.DestroyTimer]]''
+
=== Apply ===
Current object applies specified object. The effect depends on the object being applied, which can be a potion, a trigger, ...
Arguments:
@@ -399,64 +419,201 @@
Return value:
* 0: player or monster can't apply objects of that type
* 1: has been applied, or there was an error applying the object
* 2: objects of that type can't be applied if not in inventory
+
=== Cast ===
+ Current object casts a spell.
+
+ Arguments:
+ * ''Crossfire.Object'' representing the spell to case
+ * ''Crossfire.Direction'', direction in which the object should cast
+ * ''String'', optional arguments to the spell (for food creation, ...)
+
+ Return value:
+ * 0 if spell wasn't cast
+ * non-zero value if spell was cast
+
+ Note that all checks related to spell-casting apply: enough sp/gp, knowing the skill, sufficient level, spot where magic isn't forbidden, ...
+
+ The spell needn't be known to be known to be cast, though.
+
=== CastAbility ===
+
+ Equivalent of ''Cast''.
+
=== CheckArchInventory ===
+ Finds an object in current object's inventory.
+
+ Arguments:
+ * ''String'' representing the object name to find
+
+ Will return the first object in inventory that has the specified name. Name must be the raw name, without bonuses and such.
+
=== CheckInventory ===
+ Finds an object in current object's inventory.
+
+ Arguments:
+ * ''String'' representing the object to find
+
+ Will return the first object in inventory that has the specified name. Matching is done on archetype, and also partial full name match
+
=== CheckTrigger ===
+ Checks if current object should/can react to another object moving on it.
+
+ Arguments:
+ * ''Crossfire.Object'', ''cause'' that can cause current Object to react (altar, ...)
+
+ Return value:
+ * for TRIGGER_ALTAR objects, 1 if ''cause'' was destroyed, 0 if not.
+ * TRIGGER: 1 if handle could be moved, 0 if not.
+ * TRIGGER_BUTTON, TRIGGER_PEDESTAL: 0.
+
=== CreateObject ===
+ Create an object inside the current object.
+
+ Arguments:
+ * ''String'' which is the name of the object to create
+
+ Will create a new ''Crossfire.Object'' from specified name (like ''[[cfpython#Crossfire.CreateObjectByName|Crossfire.CreateObjectByName]]'') and insert it into the current object.
+
=== Drop ===
Current object drops specified object, which will be put on the ground, or in a container, depending on applied containers.
Argument:
* ''Crossfire.Object'' to drop
+
=== Fix ===
Current object is reinitialized from its default values, values (ac, wc, Str, ...) are recomputed from items worn, in inventory, ...
+
=== ForgetSpell ===
+ Player forgets a spell.
+
+ Arguments:
+ * ''Crossfire.Object'' representing the spell to forget
+
+ Object forgetting should be a player.
+
=== GetResist ===
Gets the value of a resistance to an attacktype.
Arguments:
* ''Number'': attacktype for which to get the resistance
Return: ''Number'' with the value. Note that an invalid attacktype will return 0, which can't be distinguished from a neutral resistance.
+
=== InsertInto ===
+ Insert the current object into another object.
+
+ Arguments:
+ * ''Crossfire.Object'', in which the current object will be inserted
+
+ Return:
+ * ''Crossfire.Object'' representing the newly inserted object.
+
+ After using this function, you should not use the initial ''Crossfire.Object'', as it can be merged with others.
+
=== KnowSpell ===
+ Checks if current object knows a spell.
+
+ Arguments:
+ * ''String'', name of the spell to check for
+
+ Return:
+ * ''Crossfire.Object'' representing the spell the object known, or ''None'' if this spell isn't known to the currect ''Crossfire.Object''.
+
=== LearnSpell ===
+ Make the current object learn a spell.
+
+ Arguments:
+ * ''Crossfire.Object'' representing the spell to learn
+
+ There is no learning failure. Note that any spell can be learned this way. Player will receive the message that the spell was learnt correctly.
+
=== OutOfMap ===
+ Check a position on the object's map.
+
+ Arguments:
+ * ''Number'', ''x'' and ''y'' coordinates
+
+ Return:
+ * 1 if coordinates are in the map the current object is on
+ * 0 else
+
+ Note that this function takes into account maps tiling.
+
=== Pay ===
+ Buys an item.
+
+ Arguments:
+ * ''Crossfire.Object'' to buy
+
+ Return value:
+ * 1 if item could be bought
+ * 0 else
+
+ This function applies bargaining skill if applicable, and will handle shop-based price difference. Note that the object to buy doesn't need to have the FLAG_UNPAID set.
+
=== PayAmount ===
+ Pays money.
+
+ Arguments:
+ * ''Number'', amount to pay for, in raw value units (silver coin)
+
+ Return:
+ * 1 if object could pay specified amount
+ * 0 else
+
=== QueryCost ===
+ Finds the price of an object.
+
+ Arguments:
+ * ''Crossfire.Object'' that current ''Crossfire.Object'' wants to know the price of
+ * ''Number'', flags to apply, combination of ''Crossfire.CostFlag'' values
+
+ Return value:
+ * price of the item
+
=== QueryName ===
Return: ''String'' containing the object's full name.
+
=== ReadKey ===
Reads key associated to value.
Arguments:
* ''String'': key value to read
Return: ''String'' containing the value. Will be empty if NULL value.
+
=== Remove ===
Destroys current object, which then becomes invalid.
+
=== Reposition ===
+ Moves current object to specified position on its current map.
+
+ Arguments:
+ * ''Number'', ''x'' and ''y'', coordinates of position to teleport the object to
+
=== Say ===
Current object says something in current map.
Argument:
* ''string'' to say.
+
=== Speak ===
Current object says something in current map
- FIXME difference with say??
Argument:
* ''string'' to say.
+
+ Equivalent to ''Say''.
+
=== Take ===
Current object picks up specified object, which will be put in inventory, or in a container, depending on applied containers.
Argument:
* ''Crossfire.Object'' to take
+
=== Teleport ===
Teleports the object to specified place.
Arguments:
@@ -464,15 +621,17 @@
* ''Number'': x coordinates
* ''Number'': y coordinates
Return value: ''Number'', 0 for success, 1 for failure.
+
=== WriteKey ===
Inserts specified key/value in the object.
Arguments:
* ''String'': key value
* ''String'': value to associate to the key
* ''Number'' (optional): 0 to only update the key and not insert it, non zero to add it anyway
+
===== Crossfire.Map methods and attributes =====
Properties in **bold** are read-write, others read only.
* Difficulty: ''Number''
* **Path**: ''String''
@@ -498,50 +657,105 @@
* Message: ''String''
* Region: ''Crossfire.Region''
* Exists (special meaning, ''False'' if cf map has been freed from memory, ''True'' otherwise)
- Methods:
- * Print: argument are ''String'', optional ''Number''. Prints the specified message to all players on the map, with specified flags (default is NDI_BLUE|NDI_UNIQUE). {FIXME} add flag description / equivalent of ext_info_map().
- * ObjectAt: arguments are ''x'' and ''y''. Returns the first ''Crossfire.Object'' at specified location, other objects available through the use of the ''Above'' field
- * CreateObject: arguments are ''name'', ''x'' and ''y''. Equivalent of calling ''Crossfire.CreateObjectByName()'' (creates an item from archetype or name) and insert it in the map at the specified location
- * Check
- * ChangeLight: argument is a ''Number'', specifying how to change the light. Negative value means map gets brighter, positive darker. Note that light will never be negative or over 5 (''MAX_DARKNESS'')
+ ==== Print ====
+ Prints the specified message to all players on the map.
+
+ Arguments:
+ * ''String'', message to print
+ * ''Number'', optional flags, combination of ''Crossfire.MessageFlag'' (default is NDI_BLUE|NDI_UNIQUE).
+
+ ==== ObjectAt ====
+ Returns the first ''Crossfire.Object'' at specified location.
+
+ Arguments:
+ * ''Number'', ''x'' and ''y''
+
+ Other objects on the position are available through the use of the ''Above'' field.
+
+ ==== CreateObject ====
+ Creates an object on the map.
+
+ Arguments:
+ * ''String'', name of object to create
+ * ''Integer'', ''x'' and ''y'', coordinates
+
+ Equivalent of calling ''Crossfire.CreateObjectByName()'' (creates an item from archetype or name) and inserting it in the map at the specified location
+
+ ==== Check ====
+ Arguments:
+ * ''String'', name of object to check for. Should be a raw name, without the bonuses and title and such.
+ * ''Integer'', optional ''x'' and ''y'' coordinates
+
+ Return:
+ * the first object at the specified location matching specified name
+
+ ==== ChangeLight ====
+ Change the map's light level.
+
+ Arguments:
+ * ''Number'', specifying how to change the light. Negative value means map gets brighter, positive darker.
+
+ Note that light will never be negative or over 5 (''MAX_DARKNESS'')
+
===== Crossfire.Player methods and attributes =====
This class inherits from Crossfire.Object, and introduces the new properties (bold = read-write):
* IP: ''String''.
* **BedMap**: ''string'' containing the map in which the player last saved.
* **BedX** : ''number'' containing the x coordinate of last savebed.
* **BedY** : ''number'' containing the y coordinate of last savebed.
* **MarkedItem**: ''Crossfire.Object'', item the player has marked.
* **Party**: ''Crossfire.Party'', party in which the player is. Note that changing it bypasses a potential party's password.
- and methods:
- * Message
- * Write
+
+ ==== CanPay ====
+ Checks if player can pay for unpaid items in inventory.
+
+ Return value:
+ * 1 if can pay
+ * 0 else
+
+ This will print suitable messages if player can't pay.
+
+ ==== Message ====
+ Sends a message to the player.
+
+ Arguments:
+ * ''String'', message to say
+ * ''Number'', optional, combination of ''Crossfire.MessageFlag'', default value is ''NDI_UNIQUE + NDI_ORANGE''.
+
+ ==== Write ====
+
+ Equivalent of Message.
===== Crossfire.Party methods and attributes =====
This class merely encapsulates a party. Everything is read-only. Attributes:
* Name: ''String''
* Password: ''String''
* Next: ''Crossfire.Party''
- Methods:
- * GetPlayers: ''list'' of ''Crossfire.Players''
+ ==== GetPlayers ====
+ Return value: a ''list'' of ''Crossfire.Players''
+
===== Crossfire.Region methods and attributes =====
This class encapsulates an ingame region. Properties are read-only.
* Name: ''String''
* Longname: ''String''
* Message: ''String''
* Next: ''Crossfire.Region''
- Methods:
- * Parent: returns a ''Crossfire.Region''
+ ==== Parent ====
+ Return value: a ''Crossfire.Region'', or ''None'' if no parent region.
+
====== Scripts part of Crossfire default maps ======
Those Python scripts reside in the [[http://crossfire.svn.sourceforge.net/viewvc/crossfire/maps/trunk/python/|python]] subdirectory of the maps tree. They provide additional functionality, and may be considered as always present.
FIXME {describe existing ones}
+
===== /python/misc/death_message.py =====
This script makes the monster/living thing containing it display a message when it dies. It should be hooked through an ''event_death'' archetype in monster's inventory.
Message is specified in event object's options field. It can contain %m and %k, which will be replaced by respectively dead item's name and killer's name (if no killer, replaced by an empty string).
+
===== /python/misc/greet_message.py =====
This script makes the monster/living thing containing it display a message when it attacks for the first time an enemy. It should be hooked through an ''event_time'' archetype in monster's inventory.
Message is specified in event object's options field. It can contain %m and %e, which will be replaced by respectively monster's name and enemy's name.
IP-Address : 82.236.87.204
Old Revision: http://wiki.metalforge.net/doku.php/cfpython?rev=1177088959
New Revision: http://wiki.metalforge.net/doku.php/cfpython
--
This mail was generated by DokuWiki at
http://wiki.metalforge.net/
More information about the crossfire-wiki
mailing list