[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