Lua functions

StartHeroicOpportunity

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

Historical signature: StartHeroicOpportunity(caster, class_id)

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

Function: StartHeroicOpportunity(caster, class_id[, target_override])

Description: Start a heroic opportunity with the caster based on the class_id.

Parameters:

  • caster (Spawn) - Spawn object representing caster.
  • class_id (uint8) - Integer value class_id.
  • target_override (Spawn, optional) - Used only when the caster has no selected target; an existing selected target takes precedence.

Returns: None.

Connection lifetime: Each player or group-member connection resolved by this function is retained through the native call. A disconnect or reconnect during a callback cannot destroy that retained connection or switch the ongoing call to a replacement. A later Lua call resolves the current connection. This does not extend the lifetime of unrelated spawn or item userdata.

Selected target lifetime: The caster's selected target is borrowed once and retained by the active protected callback before heroic-opportunity work. The operation keeps that original allocation through callback reentry. An explicit target override still uses its accepted Spawn argument. Saved userdata does not keep retired actors alive between callbacks. See Lua actor lifetime.

Selection identity: The caster's stored selection remembers the originally chosen actor allocation. A retired selection cannot resolve to a different actor with the same runtime ID before this operation starts. An explicit target override continues to use its accepted Spawn argument. See Lua actor lifetime.

Checked example

Active call in a local runtime Lua script. Target override is optional. This is a contextual call pattern, not a tested standalone script.

StartHeroicOpportunity(Caster, 1)

Evidence: server/Spells/Fighter/FightingChance.lua:21; binding EQ2Emu_lua_StartHeroicOpportunity.

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