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 Python's official web site.

Also, advanced functions can require some knowledge of Crossfire's inner workings. Developers seeking help should check Crossfire's page on development or 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 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.

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.

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

Python plugin is a server plugin, thus you need to insert in this object one of the event_xxx archetype (see /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.

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

Check Crossfire.RegisterCommand.

The return value of the script can be manipulated through the GetReturnValue and SetReturnValue functions. Signification of this value depends on the event being handled.

Those Python scripts reside in the python subdirectory of the maps tree. They provide additional functionality, and may be considered as always present. {describe existing ones}

Script location: /python/CFDialog.py

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

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

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.

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.

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 time of day based python scripts

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

Scripts location: /python/quests, and various archetypes (quest_ ones).

Those scripts are intended to help write quests. See the relevant guide for more information.

To use the crossfire module, add to your python script:

import Crossfire

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 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 include/attack.h
• AttackTypeNumber: ATNR_xxx constants, as defined in include/attack.h
• CostFlag: F_xxx constants, as defined in include/define.h (without the F_ prefix)
• Direction: contains NORTH, NORTHEAST, …, NORTHWEST
• EventType: EVENT_xxx constants, as defined in include/plugin.h
• MessageFlag: NDI_xxx constants, as defined in include/newclient.h
• Move: movement types, as defined in include/define.h
• Type: object type, as defined in include/define.h
• ReplyType: the rt_xxx constants, reply type, as defined in include/dialog.h
• AttackMovement: the various DISTATT, PETMOVE and other constants in the “MONSTER_MOVEMENT” group as defined in include/define.h

MessageFlag and Move can be combined, using +, to build multiple values.

{} do a nice table, with link to values?

Example:

whoami.Say("%s => %d"%(Crossfire.DirectionName[Crossfire.Direction.NORTH], Crossfire.Direction.NORTH))

will write

NORTH => 1

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.

Returns the Crossfire.Object from which the event being handled was raised, corresponds to the 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.

Returns the Crossfire.Object having caused the event being handled, corresponds to the 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.

• Move a player onto a map

Returns the Crossfire.Object being part of the event, corresponds to the third parameter of the event. Can be None.

Returns the String that was sent as part of the event, corresponds to the message parameter of the event.

Returns the absolute path of the currently executing script.

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

Crossfire.Object representing the event object that links to the plugin. Will be None for global events and custom commands.

Return current return value.

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.

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.

Returns an integer representing the Python plugin version.

Returns the system directory containing the maps. Note that it is relative to the Data directory.

Returns the system directory where unique items and maps are stored.

Returns the system directory where temporary files are stored.

Returns the system directory containing configuration files.

Returns the system directory containing read/write files.

Returns the system directory containing player files.

Returns the system directory containing read-only data.

Parameter:

• player name (string)

Returns a 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.

Returns a Python list containing Crossfire.Archetype objects representing all archetypes the server knows. Should not be called lightly, as this can take some time.

Returns a Python list containing Crossfire.Map objects, one for each map currently being loaded. This includes random and unique maps.

Returns a Python list containing Crossfire.Party objects, one for each existing party on the server.

Returns a Python list containing Crossfire.Region objects, one for each region.

Returns a list of Crossfire.Object representing all items on the friendly list. Individual objects can be added/removed through their Friendly flag.

Returns a list containing Crossfire.Players objects, one for each player on the server

Returns a Python list corresponding to the in-game server time. Fields are (start at 0 to access):

1. year
2. month
3. day
4. hour
5. minute
6. day of week
7. week of month
8. season

Parameter:

• map path (String)

Returns the Crossfire.Map with specified path, or None if such a map isn't loaded. Will not try to load the map, see Crossfire.ReadyMap for that.

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.

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.

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

• Move a player onto a map

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

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.

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.

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:

Crossfire.Log(Crossfire.LogDebug,'Player %s entered guild %s' %obj.Name %guildName)

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 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. {can NULL be passed?}

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.

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.

Removes a timer created through a call to Crossfire.Object.AddTimer.

Arguments:

• Number: timer identifier.

Returns:

• 0: no error.
• -1: invalid timer identifier.

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.

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.

Parameters:

• string to be searched
• pattern to search for

Returns 1 if string matches the pattern, 0 else.

Pattern can be a regular expression specifications

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.

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.

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.

(trunk only)

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.

All classes below are part of Crossfire module

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().

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)

archetype to which this archetype is linked. Will be None if not applicable.

archetype's name

next archetype in the archetype list. Will be None for last item

next archetype linked to current archetype. Will be None for last item

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.

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, adjusted for the number of objects. Settings this property changes both the singular and plural names
• 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
• Race: String
• Map: 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, writable on master
• 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: Crossfire.Archetype
• OtherArchetype: 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: 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: 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: Crossfire.Object this item is currently looking into ; only used for players, mostly

document all parameters. Link to relevant Crossfire function. Split in “standard function” and “helper function”?

Current object springs like a trap, hitting the victim.

Arguments:

• Crossfire.Object that is the victim of the trap.

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

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

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)

Current object casts a spell.

Arguments:

• Crossfire.Object representing the spell to cast
• 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.

Obsolete, will be removed, use Cast.

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.

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.

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.

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.

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 Crossfire.CreateObjectByName) and insert it into the current object.

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

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

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

Current object is reinitialized from its default values, values (ac, wc, Str, …) are recomputed from items worn, in inventory, …

Player forgets a spell.

Arguments:

• Crossfire.Object representing the spell to forget

Object forgetting should be a player.

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.

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.

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.

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.

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

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

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.

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.

Pays money.

Arguments:

• Number, amount to pay for, in raw value units (silver coin)

Return:

• 1 if object could pay specified amount
• 0 else

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

Return: String containing the object's full name.

Reads key associated to value. See Crossfire.WriteKey for an example of use.

Arguments:

• String: key value to read

Return: String containing the value. Will be empty if NULL value.

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.

Moves current object to specified position on its current map.

Arguments:

• Number, x and y, coordinates of position to teleport the object to

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.

Current object says something in current map

Argument:

• string to say.

Equivalent to Say.

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.

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

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.

• Move a player onto a map

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:

• 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:

Crossfire.WhoAmI.WriteKey('charged_status', 'overcharged', 1)

Crossfire.WhoAmI.ReadKey('charged_status')

This example first sets a key on the WhoAmI object, and then gets that key (returning the string 'overcharged').

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

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

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.

Creates an object on the map.

Arguments:

• String, arch name of object to create
• 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.

Example of format:

examplemap.CreateObject('tree5', (3, 8))

Arguments:

• String, name of object to check for. Should be a raw arch name, without the bonuses and title and such.
• Tuple, containing an x Integer and a y Integer, as coordinates

Return:

• the first object at the specified location matching specified arch name

Example of format:

examplemap.Check('tree5', (3, 8))

No arguments.

Return the next map in the list of active maps.

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)

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, …)

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, …)

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.

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.
• Transport: Crossfire.Object read-only field for the transport object that the player is currently controlling or aboard

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.

Sends a message to the player.

Arguments:

• String, message to say
• Number, optional, combination of Crossfire.MessageFlag, default value is NDI_UNIQUE + NDI_ORANGE.

Equivalent of Message.

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

(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)

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

(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

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

(trunk only)

Give a knowledge item to the player.

Arguments:

• knowledge: string, representing some specific knowledge item.

This class merely encapsulates a party. Everything is read-only. Attributes:

• Name: String
• Password: String
• Next: Crossfire.Party

Return value: a list of Crossfire.Players

This class encapsulates an in-game region. Properties are read-only.

• Name: String
• Longname: String
• Message: String
• Next: Crossfire.Region deprecated, will be None on master branch
• JailX, JailY: Integer, coordinates of the jail for this region (trunk only)
• JailPath: String, path of the jail for this region (trunk only)

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

A section

This script will send its activator to jail, placing them in the 15 minute cell.

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)

write an example

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