Spell Engine Internals

Relevant classes

There are three main data classes used to represent spells:

• PySpell
• SpellPacket
• SpellEntry

PySpell

This is the object that is passed to the vanilla ToEE Python API for spell scripts (spellXXX.py).
Methods
Propeties

SpellPacket

The data class storing cast spell data, including caster, target list, etc. PySpell is based on this. Temple+ exposes this class directly to the Python layer.
Python API: tpdp.SpellPacket

SpellEntry

The data class containing spell rules (parsed from rules/spells/XXX - XXX.txt).
Python API: tpdp.SpellEntry

The Active Spell List (ASL)

ToEE uses a central database for all active spells, which we'll call the Active Spell List.
It is a hashtable containing all the SpellPackets, with the key being the spell ID. There is also a separate database for PySpells, which the engine generally takes care of updating to match the data in the ASL. (TODO: exceptions to this?)

Python API

You can retrieve SpellPackets from the ASL by doing

import tpdp
spell_packet = tpdp.SpellPacket(spell_id)

In general this can fail to retrieve a valid spell.
To check validity, use:

if spell_packet.spell_enum != 0:

Spell Pruning

Spells are pruned (=unceremoniously removed) from the ASL when the engine does "cleanup".
This occurs on two occasions:

• Map Change
• Saving the game

Under what conditions are spells pruned?

• The spell is no longer marked active. (see Spell Expiry section for how this happens)
• The spell's caster object handle is null
  This will happen when the caster is not available on the current map, for any reason.
• The spell has a target list count > 0 but the first target obj handle is null.
  This indicates that the target list is no longer valid.
  Come to think of it, this alone might cause spell permanency in some situations, e.g. when AoE spells affect NPCs that are destroyed, such as summons. TODO check this...