cfpython:cfpython
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
cfpython:cfpython [2018/03/30 09:05] karl [How do I hook a script to an object?] Fix internal link |
cfpython:cfpython [2024/05/20 16:15] leaf Merge in changes from the wiki-data cfpython page |
||
|---|---|---|---|
| Line 19: | Line 19: | ||
| **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. | **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. | ||
| + | As from September, 14th, 2021, a ''.pyi'' file is available in ''maps/python/pyi''. It lists all available functions and variables, though functions aren't documented, so no parameters or description. | ||
| ====== General information ====== | ====== General information ====== | ||
| - | The plugin has access to all built-in functions of Python, and its regular libraries. Python version being used depends on the platform the server was built, but should be 2.3 or higher. FIXME {is that always true?} | + | The plugin has access to all built-in functions of Python, and its regular libraries. Python version being used depends on the platform the server was built, but must be 3 or higher. FIXME {is that always true?} |
| Using a library not part of Python's default distribution is discouraged as this introduces new dependencies. | Using a library not part of Python's default distribution is discouraged as this introduces new dependencies. | ||
| Line 39: | Line 40: | ||
| ===== How do I hook a script to an object? ===== | ===== How do I hook a script to an object? ===== | ||
| - | Python plugin is a [[:server plugin]], thus you need to insert in this object one of the //event_xxx// archetype (see ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/arch/trunk/system/|/arch/system]]'' directory). The fields to fill are: | + | Python plugin is a [[server plugin]], thus you need to insert in this object one of the //event_xxx// archetype (see ''[[https://sourceforge.net/p/crossfire/crossfire-arch/ci/master/tree/system|/arch/system]]'' directory). The fields to fill are: |
| * **title**: should be //Python// to call the Python plugin. | * **title**: should be //Python// to call the Python plugin. | ||
| * **slaying**: contains the path to the Python script to execute. Root refers to the map directory. | * **slaying**: contains the path to the Python script to execute. Root refers to the map directory. | ||
| Line 46: | Line 47: | ||
| ===== How do I hook a script to a global event? ===== | ===== How do I hook a script to a global event? ===== | ||
| - | Create a script, and put it in the ''/python/events/xxx'' subdirectory or the ''maps'' directory, where ''xxx'' is the event's name in lowercase (create the directory if it doesn't exist). Available events are listed [[server_plugin#Hooking to global events|on the server_plugin page]]. | + | Create a script, and put it in the ''/python/events/xxx'' subdirectory or the ''maps'' directory, where ''xxx'' is the event's name in lowercase (create the directory if it doesn't exist). Available events are listed [[:server_plugin#Hooking to global events|on the server_plugin page]]. |
| In addition, there is a special event, ''init'', which is called just after the plugin has been loaded. It behaves like other events in every aspect, but is called only once when the plugin finished loading. | In addition, there is a special event, ''init'', which is called just after the plugin has been loaded. It behaves like other events in every aspect, but is called only once when the plugin finished loading. | ||
| Line 140: | Line 141: | ||
| The following constant types exist: | The following constant types exist: | ||
| - | * ''AttackType'': AT_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/attack.h?view=markup|include/attack.h]]'' | + | * ''AttackType'': AT_xxx constants, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/attack.h|include/attack.h]]'' |
| - | * ''AttackTypeNumber'': ATNR_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/attack.h?view=markup|include/attack.h]]'' | + | * ''AttackTypeNumber'': ATNR_xxx constants, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/attack.h|include/attack.h]]'' |
| - | * ''CostFlag'': F_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/define.h?view=markup|include/define.h]]'' (without the F_ prefix) | + | * ''CostFlag'': F_xxx constants, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/define.h|include/define.h]]'' (without the F_ prefix) |
| * ''Direction'': contains NORTH, NORTHEAST, ..., NORTHWEST | * ''Direction'': contains NORTH, NORTHEAST, ..., NORTHWEST | ||
| - | * ''EventType'': EVENT_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/plugin.h?view=markup|include/plugin.h]]'' | + | * ''EventType'': EVENT_xxx constants, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/plugin.h|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]]'' | + | * ''MessageFlag'': NDI_xxx constants, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/newclient.h|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]]'' | + | * ''Move'': movement types, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/define.h|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]]'' | + | * ''Type'': object type, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/define.h|include/define.h]]'' |
| - | * ''ReplyType'': the rt_xxx constants, reply type, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/define.h?view=markup|include/dialog.h]]'' | + | * ''ReplyType'': the rt_xxx constants, reply type, as defined in ''[[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/define.h|include/dialog.h]]'' |
| - | * ''AttackMovement'': the various DISTATT, PETMOVE and other constants in the "MONSTER_MOVEMENT" group as defined in [[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/define.h?view=markup|include/define.h]] | + | * ''AttackMovement'': the various DISTATT, PETMOVE and other constants in the "MONSTER_MOVEMENT" group as defined in [[https://sourceforge.net/p/crossfire/crossfire-server/ci/master/tree/include/define.h|include/define.h]] |
| Line 166: | Line 167: | ||
| ===== Methods ===== | ===== Methods ===== | ||
| ==== WhoAmI ==== | ==== WhoAmI ==== | ||
| - | Returns the ''Crossfire.Object'' from which the event being handled was raised, corresponds to the ''[[server_plugin#Hooking to an object-specific event|op]]'' parameter of the event. Can be ''None''. For a map event, this is a ''Crossfire.Map'' | + | Returns the ''Crossfire.Object'' from which the event being handled was raised, corresponds to the ''[[server_plugin#Hooking to an object-specific event|op]]'' parameter of the event. Can be ''None''. For a map event, this is a ''Crossfire.Map''. For example, if the script was activated by a player applying an item, then WhoAmI points to the item. |
| ==== WhoIsActivator ==== | ==== WhoIsActivator ==== | ||
| - | Returns the ''Crossfire.Object'' having caused the event being handled, corresponds to the ''[[server_plugin#Hooking to an object-specific event|activator]]'' parameter of the event. Can be ''None''. | + | Returns the ''Crossfire.Object'' having caused the event being handled, corresponds to the ''[[server_plugin#Hooking to an object-specific event|activator]]'' parameter of the event. Can be ''None''. For example, if the script was activated by a player applying an item, then WhoIsActivator points to the player. |
| === Examples === | === Examples === | ||
| * [[cfpython#Move a player onto a map]] | * [[cfpython#Move a player onto a map]] | ||
| Line 194: | Line 196: | ||
| Sets the value the plugin will return to the server when the script exits. Value and effect depend on the event being handled. | Sets the value the plugin will return to the server when the script exits. Value and effect depend on the event being handled. | ||
| + | |||
| + | For "apply" events, ''Crossfire.SetReturnValue(0)'' will cause both the script to run and the item to be applied. ''Crossfire.SetReturnValue(1)'' will instead cause only the script to run - the apply to the item will be intercepted. For example, if a script is attached to a carrot, then ''0'' will run the script and eat the carrot, and ''1'' will run the script without eating the carrot. | ||
| ==== PluginVersion ==== | ==== PluginVersion ==== | ||
| Returns an integer representing the Python plugin version. | Returns an integer representing the Python plugin version. | ||
| Line 259: | Line 263: | ||
| ==== ReadyMap ==== | ==== ReadyMap ==== | ||
| - | Loads specified map, and returns a ''Crossfire.Map'' object wrapping it. Will return ''None'' if map couldn't be found. | + | Loads specified map, and returns a ''Crossfire.Map'' object wrapping it. Will return ''None'' if map couldn't be found. Should be used before handling that map, including when you want to teleport something. |
| Parameter: | Parameter: | ||
| Line 378: | Line 382: | ||
| ==== CostStringFromValue ==== | ==== CostStringFromValue ==== | ||
| + | (trunk only) | ||
| + | |||
| Parameters: | Parameters: | ||
| * ''amount'', long integer | * ''amount'', long integer | ||
| Line 415: | Line 421: | ||
| Properties in **bold** are read-write, others are read-only. Most properties are mapped to fields of the ''object'' structure. ''Boolean'' values are mapped to the various flags. | Properties in **bold** are read-write, others are read-only. 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 | + | * **Name**: ''String'' containing the object's name, adjusted for the number of objects. Settings this property changes both the singular and plural names |
| - | * **NamePl**: ''String'' containing the object's plural name | + | * **NamePl**: ''String'' containing the object's plural name. Changing this property only changes the item's plural name |
| + | * NameSingular: ''String'' containing the object's singular name | ||
| * **Title**: ''String'' | * **Title**: ''String'' | ||
| * **Race**: ''String'' | * **Race**: ''String'' | ||
| Line 476: | Line 483: | ||
| * Identified: ''Boolean'' | * Identified: ''Boolean'' | ||
| * **Alive**: ''Boolean'' | * **Alive**: ''Boolean'' | ||
| - | * DungeonMaster: ''Boolean'' | + | * **DungeonMaster**: ''Boolean'', writable on ''master'' |
| * WasDungeonMaster: ''Boolean'' | * WasDungeonMaster: ''Boolean'' | ||
| * **Applied**: ''Boolean'' | * **Applied**: ''Boolean'' | ||
| Line 530: | Line 537: | ||
| * **NoSave**: ''Boolean'', if set this Object will never be saved to disk, even if map is temporary swapped out | * **NoSave**: ''Boolean'', if set this Object will never be saved to disk, even if map is temporary swapped out | ||
| * Exists (special meaning, False if cf object has been freed from memory, True otherwise) | * Exists (special meaning, False if cf object has been freed from memory, True otherwise) | ||
| - | * Env: ''[[cfpython#Crossfire.Object methods and attributes|Crossfire.Object]]''. Can be ''None''. | + | * Env: ''[[cfpython#Crossfire.Object methods and attributes|Crossfire.Object]]''. Points to the object that contains this object. For example, if a player is holding a sword, that sword's Env is the player. Can be ''None''. |
| * **MoveType** | * **MoveType** | ||
| * **MoveBlock** | * **MoveBlock** | ||
| Line 597: | Line 604: | ||
| Arguments: | Arguments: | ||
| - | * ''Crossfire.Object'' representing the spell to case | + | * ''Crossfire.Object'' representing the spell to cast |
| * ''Crossfire.Direction'', direction in which the object should cast | * ''Crossfire.Direction'', direction in which the object should cast | ||
| * ''String'', optional arguments to the spell (for food creation, ...) | * ''String'', optional arguments to the spell (for food creation, ...) | ||
| Line 611: | Line 618: | ||
| ==== CastAbility ==== | ==== CastAbility ==== | ||
| - | Equivalent of ''Cast''. | + | Obsolete, will be removed, use ''Cast''. |
| ==== ChangeAbil ==== | ==== ChangeAbil ==== | ||
| Line 804: | Line 811: | ||
| ==== ReadKey ==== | ==== ReadKey ==== | ||
| - | Reads key associated to value. | + | Reads key associated to value. See ''[[cfpython#writekey|Crossfire.WriteKey]]'' for an example of use. |
| Arguments: | Arguments: | ||
| Line 812: | Line 819: | ||
| ==== Remove ==== | ==== Remove ==== | ||
| - | Destroys current object, which then becomes invalid. | + | Destroys current object, which then becomes invalid. If the object is on a map, its inventory is dropped to the ground (except no drop or god given items), else everything is destroyed. |
| ==== Reposition ==== | ==== Reposition ==== | ||
| Line 860: | Line 867: | ||
| ==== WriteKey ==== | ==== WriteKey ==== | ||
| - | Inserts specified key/value in the object. | + | Inserts specified key/value in the object. If the object is persistent (such as a player, or an item with the unique attribute set to 1), then the key will persist between server restarts. |
| Arguments: | Arguments: | ||
| Line 869: | Line 876: | ||
| **Note**: if you're not sure whether the key exists in the object, you must use ''1'' for the last argument, else the key will not be created if it doesn't exist. | **Note**: if you're not sure whether the key exists in the object, you must use ''1'' for the last argument, else the key will not be created if it doesn't exist. | ||
| + | |||
| + | **Example**: <code>Crossfire.WhoAmI.WriteKey('charged_status', 'overcharged', 1)</code> | ||
| + | <code>Crossfire.WhoAmI.ReadKey('charged_status')</code> | ||
| + | This example first sets a key on the WhoAmI object, and then gets that key (returning the string 'overcharged'). | ||
| ===== Map ===== | ===== Map ===== | ||
| Line 909: | Line 920: | ||
| Arguments: | Arguments: | ||
| - | * ''String'', name of object to create | + | * ''String'', arch name of object to create |
| - | * ''Integer'', ''x'' and ''y'', coordinates | + | * ''Tuple'', containing an ''x'' ''Integer'' and a ''y'' ''Integer'', as coordinates |
| - | Equivalent of calling ''Crossfire.CreateObjectByName()'' (creates an item from archetype or name) and inserting it in the map at the specified location | + | Equivalent of calling ''Crossfire.CreateObjectByName()'' (creates an item from archetype or name) and inserting it in the map at the specified location. |
| + | |||
| + | Example of format: | ||
| + | <code>examplemap.CreateObject('tree5', (3, 8))</code> | ||
| ==== Check ==== | ==== Check ==== | ||
| Arguments: | Arguments: | ||
| - | * ''String'', name of object to check for. Should be a raw name, without the bonuses and title and such. | + | * ''String'', name of object to check for. Should be a raw arch name, without the bonuses and title and such. |
| - | * ''Integer'', optional ''x'' and ''y'' coordinates | + | * ''Tuple'', containing an ''x'' ''Integer'' and a ''y'' ''Integer'', as coordinates |
| Return: | Return: | ||
| - | * the first object at the specified location matching specified name | + | * the first object at the specified location matching specified arch name |
| + | |||
| + | Example of format: | ||
| + | <code>examplemap.Check('tree5', (3, 8))</code> | ||
| ==== Next ==== | ==== Next ==== | ||
| Line 970: | Line 987: | ||
| * **MarkedItem**: ''Crossfire.Object'', item the player has marked. | * **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. | * **Party**: ''Crossfire.Party'', party in which the player is. Note that changing it bypasses a potential party's password. | ||
| + | * **Transport**: ''Crossfire.Object'' read-only field for the transport object that the player is currently controlling or aboard | ||
| ==== CanPay ==== | ==== CanPay ==== | ||
| Line 1068: | Line 1086: | ||
| * Longname: ''String'' | * Longname: ''String'' | ||
| * Message: ''String'' | * Message: ''String'' | ||
| - | * Next: ''Crossfire.Region'' | + | * <del>Next: ''Crossfire.Region''</del> deprecated, will be ''None'' on master branch |
| * JailX, JailY: ''Integer'', coordinates of the jail for this region (trunk only) | * JailX, JailY: ''Integer'', coordinates of the jail for this region (trunk only) | ||
| * JailPath: ''String'', path of the jail for this region (trunk only) | * JailPath: ''String'', path of the jail for this region (trunk only) | ||
cfpython/cfpython.txt · Last modified: 2024/05/20 16:15 by leaf
Page Tools
