Lua functions

GetSpellTargets

Registered in this checkout as EQ2Emu_lua_GetSpellTargets; implementation found at WorldServer/Lua/LuaFunctions.cpp:15377.

Historical signature: GetSpellTargets(spell)

Parameter and behavior details in the historical explanation are under review against the current implementation.

Function: GetSpellTargets(spell)

Description: Returns a snapshot of the spell's original target allocations that remain available in their original zone. Every returned actor is retained through the active callback. Missing, retired or departed actors and entity targets that cannot receive the spell effect are omitted. The returned array is contiguous and does not follow actors with reused runtime IDs. Requires an available spell caster and zone.

Parameters:

  • spell (Spell, optional) - Spell to inspect; defaults to the current spell.

Returns: A table of Spawn references, or no value (evaluates as nil) when the spell, caster or zone is unavailable.

Spell caster lifetime: When this function reads a spell's caster, it retains that allocation for the native operation. Retirement or callback reentry cannot replace its caster with a different allocation at the same address or runtime ID. A known expired or cleared caster is not rediscovered through a replacement connection. An actor already owned by the active callback remains usable through that callback. See Lua actor lifetime.

Original spell targets: When this function uses a spell's target list, it snapshots references to the originally selected actor allocations. It skips unavailable or departed targets instead of selecting another actor with a reused runtime ID. Accepted actors remain physically retained through the active protected callback, including Lua errors; saved userdata and target records do not keep them alive between callbacks. Explicit Spawn arguments retain their existing selection behavior. See Lua actor lifetime.

Checked example

Active call in a local runtime Lua script. Falls back to the current spell context. This is a contextual call pattern, not a tested standalone script.

local targets = GetSpellTargets()

Evidence: server/Spells/Commoner/UnholyFear.lua:16; binding EQ2Emu_lua_GetSpellTargets.

Current registration: WorldServer/Lua/LuaInterface.cpp. Historical explanation: EQ2Emu Lua documentation.