Lua functions

AddSpellBonus

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

Historical signature: AddSpellBonus(Spawn, type, value)

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

Function: AddSpellBonus(Spawn, type, value)

Description:

Adds a spell bonus of the type specified. The types are defined on https://github.com/emagi/eq2emu/blob/main/docs/data_types/item_stat_types.md

Parameters:

  • spawn (Spawn) - Spawn object reference spawn.
  • type (uint16) - Integer value type.
  • value (float) - Float value value.

Returns: None.

Recipient lifetime: Application borrows the recipient before storing the bonus. During a deferred retry pass, each target is resolved once and that allocation remains retained through storage and notifications. A callback cannot redirect later types or notifications to a replacement with the same runtime ID. Pending cancellation and source revision rules still apply. 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.

A deferred bonus also remembers the original recipient. It may wait for that same allocation to become available again, but retirement or an ID reused by a different allocation discards the old request.

Checked example

Active call in a local runtime Lua script. Trailing class requirements are optional. This is a contextual call pattern, not a tested standalone script.

AddSpellBonus(Caster, 4, 5)

Evidence: server/Spells/Apperception.lua:10; binding EQ2Emu_lua_AddSpellBonus.

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