THE PYTHON PLUGIN
=================

How do I hook a script to an object ?
-------------------------------------
Use the event_xxx to specify the script to use. The base directory for the
scripts is the map directory.
The option field is unused for now.
The plugin field should be "Python" of course.
You of course need to write some Python code too... You do as usual, but
remember to add an "import CFPython" to make all crossfire-specific functions
available in your scripts.

How do I hook a global event ?
------------------------------
Each global event is bound to a specific Python script file. Those files are
located in the python/ subdirectory of your crossfire map directory. They have
specific names, too: python_xxx.py, where xxx is the name of the global event
you want to intercept. For example, a script that should be run each time a
player logs in ("login" event) should be named python_login.py.

What functions are currently supported ?
----------------------------------------
A complete list of those functions is given below.
Note to Scriptfire users: CFPython implements all the old Scriptfire functions.
Although the syntax of Python is quite different from Guile, it should not be a
problem to port your old code.

Last count (10/09/2001) result: 181 functions (not counting the various spells
and skills wrappers). This of course does not include all the Python functions,
just the crossfire-specific ones.

In the following, I use the following type naming convention:
int   : An integer;
long  : A long;
object: A crossfire object. (In fact, it is a long).
string: A character string.

A
AcquireSpell(object who, object *spell)
  Makes "who" learn the spell identified by its spellobject.
  special_prayer is denotes if this is a special prayer type spell
  which should be removed when the player changes god
  Wrappers for all crossfire spellids are available under CFPython.
  Does not return a value.

ActivateRune(object who, object what)
  Makes "who" trigger the rune "what".
  Does not return a value.

Apply(object who, object what, int flags)
  Makes object "who" do a manual apply on object "what" with the specified
  flags. Consult the crossfire source code for all available flags.
  Return value: integer.

B
BlocksView(object who)
  Checks if "who" can block the line-of-sight.
  Return value: integer.

C
CastAbility(object who, int spellid, int direction, string options)
  Makes "who" casts a spell, identified by its id, into one direction and with
  eventually some options (like "create food booze"). The spell is cast as an
  ability and thus does not use any mana point.
  Does not return a value.

CheckTrigger(object who, object what)
  Makes "who" test trigger "what".
  Does not return a value.

CastSpell(object who, object spellob, int direction, string options)
  Makes "who" casts a spell, identified by its spell object, into one
  direction and with eventually some options (like "create food booze").  Does
  not return a value.  Note that before spellob, this functions
  second parameter was an integere for spelltype.

CheckInvisibleObjectInside(object who, string id)
  Checks for the existence of an invisible object named "id" inside object
  "who".
  Return value: The object found, if any.

CreateInvisibleObjectInside()
CreateObjectInside()
CheckMap()
CheckInventory()
CreateObject()
CanSeeInvisible(object who)
  Tests if the object "who" can see invisible things.
  Return value: test result as an integer - 0 if and only if false.

CanRoll(object who)
  Tests if the object "who" can roll.
  Return value: test result as an integer - 0 if and only if false.

CanPassThru(object who)
  Tests if the object "who" has the 'pass through' ability.
  Return value: test result as an integer - 0 if and only if false.

CanPickUp(object who)
  Tests if the object "who" can be pick up stuff.
  Return value: test result as an integer - 0 if and only if false.

CanCastSpell(object who)
  Tests if the object "who" can cast spells.
  Return value: test result as an integer - 0 if and only if false.

CanUseScroll(object who)
  Tests if object "who" can read scrolls.
  Return value: test result as an integer - 0 if and only if false.

CanUseWand(object who)
  Tests if object "who" can use a magical wand.
  Return value: test result as an integer - 0 if and only if false.

CanUseBow(object who)
  Tests if object "who" can use a bow.
  Return value: test result as an integer - 0 if and only if false.

CanUseArmour(object who)
  Tests if object "who" can wear armour.
  Return value: test result as an integer - 0 if and only if false.

CanUseWeapon(object who)
  Tests if object "who" can use a weapon.
  Return value: test result as an integer - 0 if and only if false.

CanUseRing(object who)
  Tests if object "who" can use rings.
  Return value: test result as an integer - 0 if and only if false.

CanUseSkill(object who)
  Tests if object "who" can use skills.
  Return value: test result as an integer - 0 if and only if false.

CanUseRod(object who)
  Tests if object "who" can use magical rods.
  Return value: test result as an integer - 0 if and only if false.

CanUseHorn(object who)
  Tests if object "who" can use a horn (and other musical instruments)
  Return value: test result as an integer - 0 if and only if false.

CanSeeInDark(object who)
  Tests if object "who" has got infravision capabilities.
  Return value: test result as an integer - 0 if and only if false.

D
Drop()
DirectionN()
  Wrapper for the North direction.
  Return value: an integer representing the direction.

DirectionNE()
  Wrapper for the North-East direction.
  Return value: an integer representing the direction.

DirectionE()
  Wrapper for the East direction.
  Return value: an integer representing the direction.

DirectionSE()
  Wrapper for the South-East direction.
  Return value: an integer representing the direction.

DirectionS()
  Wrapper for the South direction.
  Return value: an integer representing the direction.

DirectionSW()
  Wrapper for the South-West direction.
  Return value: an integer representing the direction.

DirectionW()
  Wrapper for the West direction.
  Return value: an integer representing the direction.

DirectionNW()
  Wrapper for the North-West direction.
  Return value: an integer representing the direction.

DoKnowSpell(object *who, char *spell)
   Checks to see if 'who' knows the spell by the name of 'spell'.
   returns the spell object if they do, null if they don't.

E
F
FindPlayer()
FixObject()

ForgetSpell(object *who, char *spell)
   Causes who to forget the spell named 'spell'.  who must be a player.


G

GetMapDirectory()
  Returns the name of the base directory containing the Crossfire maps.
  You need to concatenate the result with the value returned by
  GetDataDirectory() to get an absolute path.

GetUniqueDirectory()
  Returns the name of the base directory containing the Crossfire Unique items.
  You need to concatenate the result with the value returned by
  GetLocalDirectory() to get an absolute path.

GetTempDirectory()
  Returns the name of the base directory containing temporary Crossfire files
  (like swapped-out maps)

GetConfigurationDirectory()
  Returns the name of the base directory containing Crossfire configuration
  files.

GetDataDirectory()
  Returns the name of the base directory containing the Crossfire read only data
  files.

GetLocalDirectory()
  Returns the name of the base directory containing the Crossfire read-write
  data files.

GetPlayerDirectory()
  Returns the name of the base directory containing the Crossfire players files.
  You need to concatenate the result with the value returned by
  GetLocalDirectory() to get an absolute path.

GetSkillExperience()
GetMapPath()
GetMapObject()
GetMessage(object who)
  Gets the message contained in the specified object.
  The message is what appears inside msg...endmsg tags.

GetGod(object who)
  Gets the name of the god associated with the given object.
  Usually, this will be the god "who" is worshipping.

GetWeight(object who)
  Gets the weight of the given object.

GetMap()
GetNextObject()
GetPreviousObject()
GetFirstObjectOnSquare()
GetQuantity()
GetExperience(object who)
  Gets the amount of experience associated with the object.

GetSpeed(object who)
  Gets the speed of the given object.

GetFood(object who)
  Gets the food level of the given object.

GetGrace(object who)
  Gets the grace amount of the given object.

GetReturnValue()
GetDirection()
GetLastSP(object who)
  Gets the last_sp parameter value associated with the given object.

GetLastGrace(object who)
  Gets the last_grace parameter value associated with the given object.

GetAttackType()
GetDamage(object who)
  Gets the amount of damage associated with the given object.

GetName(object who)
  Gets the 'clear name' of the given object.

GetEventOptions()
GetEventPlugin()
GetType(object who)
  Gets the type of a given object, as a numerical identifier.

GetEventHandler()
GetIP()
GetInventory()
GetInternalName()
GetAC(object who)
  Gets the Armor Class coefficient associated with the given object.

GetCha(object who)
  Gets the Charisma value of the given object.

GetCon(object who)
  Gets the Constitution value of the given object.

GetDex(object who)
  Gets the Dexterity value of the given object.

GetHP(object who)
  Gets the amount of Hit Points associated with the given object.

GetInt(object who)
  Gets the Intelligence value of the given object.

GetPow(object who)
  Gets the Power value of the given object.

GetSP(object who)
  Gets the amount of Mana possessed by the given object.

GetStr(object who)
  Gets the Strength value of the given object.

GetWis(object who)
  Gets the Wisdom value of the given object.

GetMaxHP(object who)
  Gets the Maximum amount of Hit Points the given object can get.

GetMaxSP(object who)
  Gets the Maximum amount of Mana the given object can get.

GetXPos()
GetYPos()

H
HitBack()
HasXRays()
HasStealth()
HasBeenApplied()

I
IsOutOfMap()
IsCanBePicked(object who)
  Tests if "who" can be picked up.
  Return value: test result as an integer - 0 if and only if false.

InsertObjectInside()
IsInvisible(object who)
  Tests if the given object is invisible.
  Return value: test result as an integer - 0 if and only if false.

IsAlive(object who)
  Tests if the given object is alive.
  Return value: test result as an integer - 0 if and only if false.

IsWiz(object who)
  Tests if the given object is a DM.
  Return value: test result as an integer - 0 if and only if false.

IsApplied(object who)
  Tests if the given object is applied.
  Return value: test result as an integer - 0 if and only if false.

IsUnpaid(object who)
  Tests if the given object is paid.
  Return value: test result as an integer - 0 if and only if false.

IsFlying(object who)
  Tests if the given object is flying.
  Return value: test result as an integer - 0 if and only if false.

IsMonster(object who)
  Tests if the given object is a monster.
  Return value: test result as an integer - 0 if and only if false.

IsFriendly(object who)
  Tests if the given object is in friendly mode.
  Return value: test result as an integer - 0 if and only if false.

IsGenerator(object who)
  Tests if the given object is a generator.
  Return value: test result as an integer - 0 if and only if false.

IsThrown(object who)
  Tests if the given object can be thrown.
  Return value: test result as an integer - 0 if and only if false.

IsTurnable(object who)
  Tests if the given object is Turnable.
  Return value: test result as an integer - 0 if and only if false.

IsUsedUp(object who)
  Tests if the given object is used up.
  Return value: test result as an integer - 0 if and only if false.

IsIdentified(object who)
  Tests if the given object is identified.
  Return value: test result as an integer - 0 if and only if false.

IsSplitting(object who)
  Tests if the given object can split.
  Return value: test result as an integer - 0 if and only if false.

IsUndead(object who)
  Tests if the given object is an undead.
  Return value: test result as an integer - 0 if and only if false.

IsScared(object who)
  Tests if the given object is scared.
  Return value: test result as an integer - 0 if and only if false.

IsUnaggressive(object who)
  Tests if the given object is in unaggressive mode.
  Return value: test result as an integer - 0 if and only if false.

IsOfType()
IsRunningAway(object who)
  Tests if the given object is running away.
  Return value: test result as an integer - 0 if and only if false.

IsUnique(object who)
  Tests if the given object is unique.
  Return value: test result as an integer - 0 if and only if false.

IsFloor(object who)
  Tests if the given object is a floor tile.
  Return value: test result as an integer - 0 if and only if false.

IsLifeSaver(object who)
  Tests if the given object is a LifeSaver.
  Return value: test result as an integer - 0 if and only if false.

IsSleeping(object who)
  Tests if the given object is sleeping.
  Return value: test result as an integer - 0 if and only if false.

IsConfused(object who)
  Tests if the given object is confused.
  Return value: test result as an integer - 0 if and only if false.

IsCursed(object who)
  Tests if the given object is cursed.
  Return value: test result as an integer - 0 if and only if false.

IsDamned(object who)
  Tests if the given object is damned.
  Return value: test result as an integer - 0 if and only if false.

IsKnownMagical(object who)
  Tests if the given object is known to be a magical one.
  Return value: test result as an integer - 0 if and only if false.

IsKnownCursed(object who)
  Tests if the given object is known to be a cursed one.
  Return value: test result as an integer - 0 if and only if false.

IsBlind(object who)
  Tests if the given object is blind.
  Return value: test result as an integer - 0 if and only if false.

J
K
KillObject()

L
LoadObject()

M
MatchString()
Message()
MakeInvisible()

N
O
OnlyAttack()

P
PickUp()

Q
R
ReadyMap()
ReflectMissiles()
ReflectSpells()
RemoveObject()
RegisterCommand()

S
SetQuantity()
SetName()
SetMessage()
SetSkillExperience()
SetCursed()
SetUnaggressive()
SetGod()
SetWeight()
Say()
SetInvisible()
SetSpeed()
SetFood()
SetGrace()
SetReturnValue()
SetDirection()
SetLastSP()
SetLastGrace()
SetFace()
SetAttackType()
SetDamage()
SetBeenApplied()
SetIdentified()
SaveObject()
SetEventHandler()
SetEventPlugin()
SetEventOptions()
SetPosition()
SetNickname()
SetAC()
SetCha()
SetCon()
SetDex()
SetHP()
SetInt()
SetMaxHP()
SetMaxSP()
SetPow()
SetSP()
SetStr()
SetWis()
StandStill()

T
Take()
Teleport()

U
V
W
WhoAmI()
WhoIsActivator()
WhatIsMessage()
Write()
WhoIsOther()
WasWiz()

X
Y
Z

Chachkoff Y.

yann.chachkoff@mailandnews.com
