Crossfire Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== CFPython ======
<WRAP lo>
(Note: It would be nice if there were more code examples on this page. ((
For instance bla.WriteKey("buildinghp", 100, 1) does not insert the key value "buildinghp 100" into bla. It would be nice to know what is wrong here since this wiki suggests that's how it's to be done. More code examples would clear up any confusion and allow new developers to more quickly pick up cf-python.) )) ) \\
[As of march 2013 this note is outdated. Also, see some examples at the bottom of this page.]
</WRAP>

The Crossfire 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.

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/development/index.html|Crossfire's page on development]] or [[http://crossfire.real-time.com/resources/index.html|Crossfire's resource page]] (which includes links to lists, IRC, how to contact people, ...). 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 ======
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?}

Using a library not part of Python's default distribution is discouraged as this introduces new dependencies.

Scripts execute in their own context, and their state information is not kept between runs. There are functions to persist data, or share between scripts. Note that data persisted through those functions will not survive a server restart.

Scripts should import the ''Crossfire'' module to access Crossfire's built-in functions.

Calling Crossfire functions with invalid arguments will result in a Python exception being raised. A function failure will also result in an exception.

Scripts will have the same access rights as the server itself. It may be able to write to some directories, but not others.

Data that should survive a server restart should be persisted in the ''PlayerDirectory'' (for specific player information) or ''DataDirectory'' (for regular information), where the server normally has write access.

Scripts for server releases after 9 November 2007 should prefer the use of new [[cfpython#Log|Crossfire.Log(level,message)]] method over the python build-in print method. The reason of this is to keep coherency between python scripts messages and server logging.

===== 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:
  * **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.

A script can then use ''WhoAmI()'', ''WhoIsActivator()'', ''WhoIsOther()'', ''WhatIsMessage()'' functions of the ''Crossfire'' module to find the executing context.

===== 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]].
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.

===== How do I register a custom command? =====
Check ''[[cfpython#RegisterCommand|Crossfire.RegisterCommand]]''.

===== Return value =====
The return value of the script can be manipulated through the ''[[cfpython#GetReturnValue|GetReturnValue]]'' and ''[[cfpython#SetReturnValue|SetReturnValue]]'' functions. Signification of this value depends on the event being handled.

====== 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}

===== Dialog Helper =====
Script location: ''/python/CFDialog.py''

This script provides two utility classes a map maker can use to easily create complex dialogs.
Go [[cfdialog#here]] for a complete explanation on how it works.

===== Death message =====
Script location: ''/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).

===== Greeting message =====
Script location: ''/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.


===== Experience rewarder =====
Script location: ''/python/items/experience_rewarder.py''

This script will give experience to the "activating" player. It should be linked through the "trigger" event of an altar, or similar thing.

Options are specified in the event object's fields.

A key/value will be used to store in the player if she activated the item already.

Available options are:
  * exp: experience to gain
  * skill: skill to add experience to. Can be empty, in which case exp is given to the general exp only
  * wc: what to do when the player doesn't know the skill:
     * 0: give the player the skill
     * 1: give player exp to total, no skill
     * 2: player gets nothing
  * race: if set, the player can only use once this item.

===== Time of the day =====
Scripts location: ''/python/tod/*.py''

Those scripts add behaviour to items based on time of the day. Want to open doors at specific time, make werewolfes, deactivate a magic_mouth during the Season of Winter? Those scripts are ready to use. See [[cfpython:tod|time of day based python scripts]]


===== Hall of fame =====
Script location: ''/python/misc/hall_of_fame.py'' (trunk)

This script is intended to be bound to event objects, generally the apply one.

If the item this script is bound to is a SIGN, then it will display its list of players, preceded by the own item's message (as header).

For any other item, the player is added to the list, with her title. If the event object itself has a message, it will be displayed to the player if she is added to the list.

The script's parameters is the internal name of the quest, which must be suitable for a file name (no conversion done).

===== Quest support scripts =====
Scripts location: ''/python/quests'', and various archetypes (''quest_'' ones).

Those scripts are intended to help write quests. See [[:user:cavesomething:guide_to_quest_dialogs|the relevant guide]] for more information.

====== Crossfire module ======

To use the crossfire module, add to your python script:
<code python>
import Crossfire
</code>


The following functions and objects are available to all scripts using the Crossfire module through ''import Crossfire''.

**Convention:** in the reference, ''xxx()'' specifies a method, ''xxx'' specifies a property.


===== Constants =====
Constants are available to wrap values used in Crossfire code like object types, movements, ...
They are available through ''Crossfire.xxx.VALUE'', where ''xxx'' is the constant type and ''VALUE'' the value as in the C source code, in uppercase, without specific prefix (ie F_TRUE becomes TRUE, AT_FIRE becomes FIRE, and so on).

For each constant group ''xxx'' there exists a ''xxxName'' dictionary object containing the name of the value as a string.

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]]''
  * ''AttackTypeNumber'': ATNR_xxx constants, as defined in ''[[http://crossfire.svn.sourceforge.net/viewvc/crossfire/server/trunk/include/attack.h?view=markup|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)
  * ''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]]''
  * ''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]]''
  * ''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]]''
  * ''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]]


''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>
will write <code>NORTH => 1</code>

**Warning**: Python doesn't know about constants, thus scripts can modify those values. Doing this can lead to weird results, and should be avoided at all cost. Note that the C code itself is immune to the changes, only the scripts would suffer.

===== Methods =====
==== 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''

==== 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''.
=== Examples ===
  * [[cfpython#Move a player onto a map]]

==== WhoIsOther ====
Returns the ''Crossfire.Object'' being part of the event, corresponds to the ''[[server_plugin#Hooking to an object-specific event|third]]'' parameter of the event. Can be ''None''.
==== WhatIsMessage ====
Returns the ''String'' that was sent as part of the event, corresponds to the ''[[server_plugin#Hooking to an object-specific event|message]]'' parameter of the event.
==== ScriptName ====
Returns the absolute path of the currently executing script.
==== ScriptParameters ====
This ''String'' variable contains:
  * for a global event, the name of the event (''born'', ''gkill'', ...)
  * for an event hooked to an object, the ''name'' field of the object
  * for a custom command, the parameters the player sent
==== WhatIsEvent ====
''Crossfire.Object'' representing the event object that links to the plugin. Will be ''None'' for global events and custom commands.

==== GetReturnValue ====
Return current return value.
==== SetReturnValue ====
Parameters:
  * return value (integer)

Sets the value the plugin will return to the server when the script exits. Value and effect depend on the event being handled.
==== PluginVersion ====
Returns an integer representing the Python plugin version.
==== MapDirectory ====
Returns the system directory containing the maps. Note that it is relative to the ''Data'' directory.
==== UniqueDirectory ====
Returns the system directory where unique items and maps are stored.
==== TempDirectory ====
Returns the system directory where temporary files are stored.
==== ConfigDirectory ====
Returns the system directory containing configuration files.
==== LocalDirectory ====
Returns the system directory containing read/write files.
==== PlayerDirectory ====
Returns the system directory containing player files.
==== DataDirectory ====
Returns the system directory containing read-only data.

==== FindPlayer ====
Parameter:
  * player name (string)

Returns a ''[[cfpython#crossfire.player_methods_and_attributes|Crossfire.Player]]'' object for specified player, based on partial name matching, or ''None'' if not found. If only one player name can match, return this player, else return ''None''.
==== GetArchetypes ====
Returns a Python ''list'' containing ''[[cfpython#crossfire.archetype_methods_and_attributes|Crossfire.Archetype]]'' objects representing all archetypes the server knows. Should not be called lightly, as this can take some time.
==== GetMaps ====
Returns a Python ''list'' containing ''[[cfpython#crossfire.map_methods_and_attributes|Crossfire.Map]]'' objects, one for each map currently being loaded. This includes random and unique maps.
==== GetParties ====
Returns a Python ''list'' containing ''[[cfpython#crossfire.party_methods_and_attributes|Crossfire.Party]]'' objects, one for each existing party on the server.

==== GetRegions ====
Returns a Python ''list'' containing ''[[cfpython#crossfire.region_methods_and_attributes|Crossfire.Region]]'' objects, one for each region.
==== GetFriendlyList ====
Returns a ''list'' of ''[[cfpython#crossfire.object_methods_and_attributes|Crossfire.Object]]'' representing all items on the friendly list. Individual objects can be added/removed through their ''Friendly'' flag.
==== GetPlayers ====
Returns a ''list'' containing ''[[cfpython#crossfire.player_methods_and_attributes|Crossfire.Players]]'' objects, one for each player on the server
==== GetTime ====
Returns a Python ''list'' corresponding to the in-game server time. Fields are (start at ''0'' to access):
  - year
  - month
  - day
  - hour
  - minute
  - day of week
  - week of month
  - season
==== MapHasBeenLoaded ====
Parameter:
  * map path (''String'')

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.

==== FindFace ====
Parameter:
  * face name (''String'')

Returns the number of the specified face, 0 if it doesn't exist. The face name is the name as it appears in the archetypes, ie ''dcross-red1.111'', without the set name or extension.

==== FindAnimation ====
Parameter:
  * animation name (''String'')

Returns the number of the specified animation, 0 if it doesn't exist. The name is has it appears in the archetypes, ie ''campfire'' or ''bat''.


==== ReadyMap ====
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:
  * ''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
=== Examples ===
  * [[cfpython#Move a player onto a map]]

==== CreateObject ====
Returns an empty object which can then be manipulated and inserted in a map.

==== CreateObjectByName ====
Parameters:
  * object or archetype name (''String'')

Returns object with specified archetype or object name, or ''None'' if no object has the name, and archetype wasn't found.
==== CreateMap ====
Parameters:
  * map width (''Number'')
  * map height (''Number'')

Returns an empty map of specified dimensions. Unless map is removed immediately, ''Path'' should be set so the map correctly displays in the ''maps'' output.


==== Log ====
Parameters:
  * level (Crossfire.LogError, Crossfire.LogInfo, Crossfire.LogDebug or Crossfire.LogMonster)
  * message (string)

Use the server logging facilities to output script messages in server console. This is the **recommended** method, instead of using the
python build-in "print" method. Using this, scripts take advantage of Debug and Monster level which can be hidden at will by server admin (log level), and
have access to the error level, mentioning to admin serious troubles.

Example:
<code>Crossfire.Log(Crossfire.LogDebug,'Player %s entered guild %s' %obj.Name %guildName)</code>
==== RegisterCommand ====
Parameters:
  * command name (string)
  * script (string)
  * speed (decimal, must be positive or 0)

Registers a server command which will be mapped to specified script. See [[server plugin#Registering a command]] for more information.

The script path is relative to the ''maps'' subdirectory.
When the command is called, the following methods will provide information:
  * ''WhoAmI'' contains the player
  * ''ScriptName'' contains the currently executing script's name
  * ''ScriptParameters'' contains any parameter the player added to the command. FIXME {can NULL be passed?}
==== RegisterGlobalEvent ====
Parameters:
  * event code (''Number'', should be one of the ''Crossfire.EventType.xxx'' constants)

This instructs the server to call the Python plugin for all events of specified type. Python will then call scripts in the ''/python/events/xxx'' directory, where ''xx'' is the event's name.

This function should not be used except in special circumstances, as Python by default registers all events anyway.
==== UnregisterGlobalEvent ====
Parameters:
  * event code (''Number'', should be one of the ''Crossfire.EventType.xxx'' constants)

This instructs the server to stop calling the Python plugin for all events of specified type.

This function should not be used, except in special circumstances, as it can disable other scripts that use those events.
==== DestroyTimer ====
Removes a timer created through a call to ''[[cfpython#AddTimer|Crossfire.Object.AddTimer]]''.

Arguments:
  * ''Number'': timer identifier.

Returns:
  * 0: no error.
  * -1: invalid timer identifier.
==== GetPrivateDictionary ====
Returns a Python ''dictionary'' the script can use to store data between runs. This data is not shared with other scripts.

Note that data will be lost in case of server restart.
==== GetSharedDictionary ====
Returns a Python ''dictionary'' the script can use to share data with other scripts.

Note that data will be lost in case of server restart.

==== MatchString ====
Parameters:
  * string to be searched
  * pattern to search for

Returns ''1'' if string matches the pattern, ''0'' else.

Pattern can be a regular expression FIXME specifications

==== AddReply ====
Parameters:
  * string that is the word the player can say
  * string that is the description of the choice

This method can only be called in a EVENT_SAY context.

Will generate an error if too many replies defined or not in an EVENT_SAY context.

==== SetPlayerMessage ====
Parameters:
  * string that is what the player will be seen as saying
  * optional ''ReplyType'' constant being the type of the message, defaults to ''ReplyType.SAY''

This method can only be called in a EVENT_SAY context.

==== NPCSay ====
Parameters:
  * ''object'' that is the NPC who will talk
  * string that is the message to say

This method can only be called in a EVENT_SAY context.

Will add an NPC reply, that will be displayed to the player when the dialog processing ends.

Will generate an error if too many messages defined or not in an EVENT_SAY context.

==== CostStringFromValue ====
Parameters:
  * ''amount'', long integer
  * ''largest coin'', integer (optional)

Return value: formatted string describing the amount, with coin descriptions.

Will return "nothing" if ''amount'' is 0.

====== Crossfire module classes =====
All classes below are part of Crossfire module
===== Archetype =====
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()''.

==== Clone ====
A ''Crossfire.Object'' property 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. 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
==== 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.





===== Object =====
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 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
  * **NamePl**: ''String'' containing the object's plural name
  * **Title**: ''String''
  * **Race**: ''String''
  * **Map**: ''[[cfpython#Crossfire.Map methods and attributes|Crossfire.Map]]'' containing the map the object is in. Changing that teleports the object to specified map, at default coordinates.
  * **Cha**: charisma
  * **Con**: constitution
  * **Dex**: dexterity
  * **Int**: intelligence
  * **Pow**: power
  * **Str**: strength
  * **Wis**: wisdom
  * **HP**: hitpoints
  * **MaxHP**: maximum hitpoints
  * **SP**: spellpoints
  * **MaxSP**: maximum spellpoints
  * **Grace**: grace
  * **MaxGrace**: maximum grace
  * **Food**: food
  * **AC**: armour class
  * **WC**: weapon class
  * **Dam**
  * Luck
  * **Exp**
  * PermExp
  * ExpMul
  * **Message**: ''String''
  * **Slaying**: ''String''
  * **Cursed**: ''Boolean''
  * **Damned**: ''Boolean''
  * **Weight**: ''Number''
  * **WeightLimit**: ''Number''
  * Above: ''Crossfire.Object''
  * Below: ''Crossfire.Object''
  * Inventory: ''Crossfire.Object''
  * Owner: ''Crossfire.Object''
  * X: ''Number''
  * Y: ''Number''
  * **Direction**: ''Number''
  * **Facing**: ''Number''
  * **Unaggressive**: ''Boolean''
  * **God**: ''String''
  * **Pickable**: ''Boolean'', whether the item can be picked up or not
  * **Quantity**: ''Number''. Setting it to 0 removes the object.
  * **Invisible**: ''Boolean''
  * **Speed**: ''Number''
  * **SpeedLeft**: ''Number''
  * **LastSP**: ''Number''
  * **LastGrace**: ''Number''
  * Level: ''Number''
  * **Face**:
    * on ''branch'': when reading, ''Number'' representing the face number. When writing, a ''String'' representing the face's name (eg: ''cobblesto1.111''). Will raise an error if invalid face.
    * on ''SVN trunk'': ''String'' representing the face's name (eg: ''cobblesto1.111''). Will raise an error if trying to set an invalid face.
  * **Anim**:
    * on ''branch'': when reading, ''Number'' representing the animation number, 0 if none. When writing, a ''String'' representing the animation's name (eg: ''fireplace''). Will raise an error if invalid animation.
    * on ''trunk'': ''String'' representing the animation's name (eg: ''campfire''). Will raise an error if trying to set an invalid animation.
  * **AnimSpeed**: ''Number'', the animation speed
  * **AttackType**: ''Number''
  * BeenApplied: ''Boolean''
  * Identified: ''Boolean''
  * **Alive**: ''Boolean''
  * DungeonMaster: ''Boolean''
  * WasDungeonMaster: ''Boolean''
  * **Applied**: ''Boolean''
  * **Unpaid**: ''Boolean''
  * Monster: ''Boolean''
  * **Friendly**: ''Boolean''
  * Generator: ''Boolean''
  * Thrown: ''Boolean''
  * **CanSeeInvisible**: ''Boolean''
  * **Rollable**: ''Boolean''
  * **Turnable**: ''Boolean''
  * **UsedUp**: ''Boolean''
  * Splitting: ''Boolean''
  * **Blind**: ''Boolean''
  * CanUseHorn: ''Boolean''
  * CanUseRod: ''Boolean''
  * CanUseSkill: ''Boolean''
  * **KnownCursed**: ''Boolean''
  * **Stealthy**: ''Boolean''
  * **Confused**: ''Boolean''
  * **Sleeping**: ''Boolean''
  * **Lifesaver**: ''Boolean''
  * Floor: ''Boolean''
  * HasXRays: ''Boolean''
  * CanUseRing: ''Boolean''
  * CanUseBow: ''Boolean''
  * CanUseWand: ''Boolean''
  * **CanSeeInDark**: ''Boolean''
  * **KnownMagical**: ''Boolean''
  * CanUseWeapon: ''Boolean''
  * CanUseArmour: ''Boolean''
  * CanUseScroll: ''Boolean''
  * CanCastSpell: ''Boolean''
  * **ReflectSpells**: ''Boolean''
  * **ReflectMissiles**: ''Boolean''
  * **Unique**: ''Boolean''
  * CanPickUp: ''Boolean'', whether the monster can pickup items or not.
  * **RunAway**: ''Boolean''
  * **Scared**: ''Boolean''
  * **Undead**: ''Boolean''
  * **BlocksView**: ''Boolean''
  * **HitBack**: ''Boolean''
  * **StandStill**: ''Boolean''
  * **OnlyAttack**: ''Boolean''
  * **MakeInvisible**: ''Boolean''
  * Money: ''Number'', returns the total money (in silver) the object owns
  * Type: ''Number''
  * Subtype: ''Number''
  * **Value**: ''Number'', value of the object
  * ArchName: ''String'', name of this object's archetype
  * Archetype: ''[[cfpython#Crossfire.Archetype methods and attributes|Crossfire.Archetype]]''
  * OtherArchetype: ''[[cfpython#Crossfire.Archetype methods and attributes|Crossfire.Archetype]]''
  * **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)
  * 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**
  * **MoveBlock**
  * **MoveAllow**
  * **MoveOn**
  * **MoveOff**
  * **MoveSlow**
  * MoveSlowPenalty
  * **Enemy**: ''[[cfpython#Crossfire.Object methods and attributes|Crossfire.Object]]'' representing the object's enemy. Will probably be ''None'' except for monsters.
  * Count
  * **GodGiven**: ''Boolean''
  * **IsPet**: if the object is on the friendly list or not
  * **AttackMovement**
  * **Duration**
  * **Skill**
  * **NoDamage**: ''Boolean''
  * **RandomMovement**: ''Boolean''
  * **GlowRadius**: Integer
  * Container: ''[[cfpython#Crossfire.Object methods and attributes|Crossfire.Object]]'' this item is currently looking into ; only used for players, mostly

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 subtracts experience to current object.

Arguments:
  * ''number'', experience to add
  * ''string'' (optional), skill to add to
  * ''number'' (optional), what to do if player doesn't have the specified skill:
    * 0: give the player the skill
    * 1: give player exp to total, no skill
    * 2: player gets nothing
    * 3: used when removing exp


==== Apply ====
Current object applies specified object. The effect depends on the object being applied, which can be a potion, a trigger, ...

Arguments:
  * ''Crossfire.Object'' to apply
  * flag FIXME meaning?

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

==== Arrest ====
Player is jailed, put in a map defined based on the region. No information is sent to victim.

Return value:
  * 0: correctly jailed
  * -1: no jail could be found (region issue)
  * -2: failure loading jail, or player already on jail's destination
  * -3: object is not a player (Type == PLAYER)

==== 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''.

==== ChangeAbil ====
Displays relevant messages about resistances and so on changes.

Arguments:
  * ''Crossfire.Object'' which is a force effect, or something that changes a player's attribute and was just added to inventory.

==== 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 what to find

Will return the first object in inventory that has the specified archetype, or the specified name (partial matches are fine), or the specified "slaying" field.




==== 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.

==== CreateTimer ====
Fires an ''event_timer'' after the specified delay. Object should have a handler for this event.

Arguments:
  * ''number'', delay for timer
  * ''number'', timer mode
    * 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]]''

==== 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

==== Event ====
Generates a ''user event'' to the object.

Arguments:
  * ''Crossfire.Object'' which is the activator of the event
  * ''Crossfire.Object'' which is the third object of the event
  * ''String'' which is the custom event's name
  * ''integer'' specifying whether to fix or not the object

==== 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.


==== Move ====
Tries to move the object in a direction.

Arguments:
  * ''Number'', direction to move to. Should be one of ''Crossfire.Direction.xxx'' value.

Return:
  * 1 if object could move
  * 0 else

==== MoveTo ====
Tries to move the object towards a specified destination. ''trunk'' only.

Arguments:
  * ''Number'', x and y coordinates of the destination

Return:
  * 2 if the object is blocked or no path to the goal
  * 1 if object could move towards the goal
  * 0 else

==== 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.  See ''[[cfpython#writekey|Crossfire.WriteKey]]'' for an example of use.

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. If in a dialog context (reacting to a SAY event), the message will be queued to be displayed after the player actually says something, to enable changing her reply. If not in a dialog context, will just display the message.

Argument:
  * ''string'' to say.

==== Speak ====
Current object says something in current map

Argument:
  * ''string'' to say.

Equivalent to ''Say''.

==== Split ====
This should only be called on stacks of objects (where Object.Quantity is greater than 1)
This takes an object with n items in it's stack, and splits it into two objects, returning the new object. This new object contains the number of items specified by the argument, the original object has its Quantity reduced by the same amount.

Argument:
  * ''Number'' how many of the item should be moved to the new object.

==== 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:
  * ''Crossfire.Map'': map to insert into.
  * ''Number'': x coordinates
  * ''Number'': y coordinates

Return value: ''Number'', 0 for success, 1 for failure.
=== Examples ===
  * [[cfpython#Move a player onto a map]]

==== WriteKey ====
Inserts specified key/value in the object.

Arguments:
  * ''String'': key value
  * ''String'': value to associate to the key
  * ''Number'' (optional, defaults to 0): if 0, the key will only be updated if it already exists in the object; if non zero, will insert it if not already existing


**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 =====
Properties in **bold** are read-write, others read only.
  * Difficulty: ''Number''
  * **Path**: ''String''
  * TempName: ''String''
  * Name: ''String''
  * ResetTime: ''Number''

  * ResetTimeout: ''Number''
  * Players: ''Number'', number of players on the map
  * Light: ''Number''
  * Darkness: ''Number''
  * Width: ''Number''
  * Height: ''Number''
  * EnterX: ''Number''
  * EnterY: ''Number''
  * Message: ''String''
  * Region: ''Crossfire.Region''
  * Unique: ''Number''

==== 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

==== Next ====
No arguments.

Return the next map in the list of active maps.

==== 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'')

==== Insert ====
Inserts an object at specified location.

Arguments:
  * ''Crossfire.Object'' to insert
  * ''Number'', X and Y, coordinates where to insert

Return: ''Crossfire.Object'' representing the inserted object. Can be ''None'' if object was removed for some reason (eaten by an altar, ...)

==== InsertAround ====
Inserts an object around a specified location, randomly choosing a free spot.

Arguments:
  * ''Crossfire.Object'' to insert
  * ''Number'', X and Y, coordinates around which to insert

Return: ''Crossfire.Object'' representing the inserted object. Can be ''None'' if object was removed for some reason (eaten by an altar, ...)

==== TriggerConnected ====
Triggers the connected value for the map, this is normally used for activating gates, etc.

Arguments:
  * ''connected'' The connection that is to be triggered.
  * ''state'' Connections have two states, push and release (or on/off), zero causes the map to be sent the release (or off) state, non-zero the ''push''
  * ''cause'' The optional object that caused the trigger to occur.
 

===== Player =====
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.

==== 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.

==== QuestStart ====
(trunk only)

TODO explain quest definitions

Signal a player that she started a quest. Note that the quest must be correctly defined in the ''default.quests'' file.

Arguments:
  * ''quest_code'': string, internal quest code.
  * ''state'': integer, state to set the quest to.

==== QuestGetState ====
(trunk only)

Query the current state of a quest for the player. Note that the quest must be correctly defined in the ''default.quests'' file.

Arguments:
  * ''quest_code'': string, internal quest code

Return:
  * quest state, 0 if not started (or was completed previously and not started again)

==== QuestSetState ====
(trunk only)

Signal a player that she advanced in a quest. Note that the quest must be correctly defined in the ''default.quests'' file.

Arguments:
  * ''quest_code'': string, internal quest code.
  * ''state'': integer, state to set the quest to.

==== QuestWasCompleted ====
(trunk only)

Query whether the player completed the quest previously. Note that the quest must be correctly defined in the ''default.quests'' file.

Arguments:
  * ''quest_code'': string, internal quest code

Return:
  * 0 if the quest was never completed, 1 else


==== KnowledgeKnown ====
(trunk only)

Query whether the player knowns through the knowledge system the specified factoid.

Arguments:
  * ''knowledge'': string, representing some specific knowledge item.

Return:
  * 1 if the player knows the item, 0 else.

==== GiveKnowledge ====
(trunk only)

Give a knowledge item to the player.

Arguments:
  * ''knowledge'': string, representing some specific knowledge item.

===== Party =====
This class merely encapsulates a party. Everything is read-only. Attributes:
  * Name: ''String''
  * Password: ''String''
  * Next: ''Crossfire.Party''

==== GetPlayers ====
Return value: a ''list'' of ''Crossfire.Players''


===== Region =====
This class encapsulates an in-game region. Properties are read-only.
  * Name: ''String''
  * Longname: ''String''
  * Message: ''String''
  * Next: ''Crossfire.Region''
  * JailX, JailY: ''Integer'', coordinates of the jail for this region (trunk only)
  * JailPath: ''String'', path of the jail for this region (trunk only)

==== Parent ====
Return value: a ''Crossfire.Region'', or ''None'' if no parent region.

====== Example Scripts ======
A section
=== Move a player onto a map ===
This script will send its activator to jail, placing them in the 15 minute cell.
<code python>
import Crossfire

#we get the the object that triggered this script
activator = Crossfire.WhoIsActivator()

#make sure that the map is loaded, and get the object representing it
#we could get the map's default entry coordinates with 'm.enter_x' and 'm.enter_y'
m = Crossfire.ReadyMap('/scorn/misc/jail')

#teleport the activating object to the x:15 y:1 coordinates of the map (m) we just readied
activator.Teleport(m, 15, 1)
</code>
=== Object.WriteKey ===
FIXME write an example

(see a working example at maps/python/monsters/farnass.py used from maps/scorn/misc/castle_kitchen )
Crossfire Wiki

User Tools

Site Tools

Page Tools
